API Evangelist conversational phrasing for Commerce Contacts API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Commerce Contacts API
  version: 1.0.0
extends: openapi/squarespace-contacts-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 11
- target: $.paths['/v1/contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List the contacts on my website
      effect: read
      questions:
      - How do I list every contact stored for my Squarespace site?
      - Can I control how many contacts come back per page when listing them all?
      instructions:
      - text: List my website's contacts, {pageSize} per page.
        slots:
          pageSize: query.pageSize
      - text: Continue listing all contacts from cursor {cursor}.
        slots:
          cursor: query.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/contacts'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a new contact
      effect: write
      questions:
      - How do I add a new person to my site's contact list?
      - What details are required when creating a contact, like locale and primary email?
      instructions:
      - text: Create a contact named {firstName} {lastName} with email {primaryEmail} and locale {locale}.
        slots:
          firstName: requestBody.firstName
          lastName: requestBody.lastName
          primaryEmail: requestBody.primaryEmail
          locale: requestBody.locale
      - text: Add {primaryEmail} as a new contact for {firstName} {lastName}, locale {locale}.
        slots:
          primaryEmail: requestBody.primaryEmail
          firstName: requestBody.firstName
          lastName: requestBody.lastName
          locale: requestBody.locale
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/contacts/query'].post
  update:
    x-apievangelist-phrasing:
      intent: Search and filter contacts
      effect: read
      questions:
      - Which contacts have placed more than a certain number of orders?
      - Can I search contacts by name or email and sort the results?
      - How do I find donors whose last donation was before a given date?
      instructions:
      - text: Search contacts matching {searchString}, sorted by {sortField} {sortDirection}.
        slots:
          searchString: requestBody.searchString
          sortField: requestBody.sortField
          sortDirection: requestBody.sortDirection
      - text: Find contacts whose order count falls within {orderCount}.
        slots:
          orderCount: requestBody.orderCount
      - text: Filter contacts by last donation date range {lastDonationOn}.
        slots:
          lastDonationOn: requestBody.lastDonationOn
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/contacts/{contactId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one contact's details
      effect: read
      questions:
      - How can I pull up the full record for a single contact by ID?
      - What information is stored on one specific contact?
      instructions:
      - text: Get contact {contactId}.
        slots:
          contactId: path.contactId
      - text: Show me the details saved for contact {contactId}.
        slots:
          contactId: path.contactId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/contacts/{contactId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact
      effect: destructive
      questions:
      - How do I remove a contact from my site entirely?
      - Can I permanently delete a single contact record by its ID?
      instructions:
      - text: Delete contact {contactId}.
        slots:
          contactId: path.contactId
      - text: Remove contact {contactId} from my contact list.
        slots:
          contactId: path.contactId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/contacts/{contactId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a contact's name, email or locale
      effect: write
      questions:
      - How do I change the email address on an existing contact?
      - Can I update just a contact's last name without resending everything else?
      instructions:
      - text: Change the primary email of contact {contactId} to {primaryEmail}.
        slots:
          contactId: path.contactId
          primaryEmail: requestBody.primaryEmail
      - text: Rename contact {contactId} to {firstName} {lastName}.
        slots:
          contactId: path.contactId
          firstName: requestBody.firstName
          lastName: requestBody.lastName
      - text: Set the locale of contact {contactId} to {locale}.
        slots:
          contactId: path.contactId
          locale: requestBody.locale
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/contacts/{contactId}/address-book'].get
  update:
    x-apievangelist-phrasing:
      intent: List a contact's saved addresses
      effect: read
      questions:
      - Which addresses are saved in a contact's address book?
      - How can I tell which saved address is a contact's default shipping address?
      instructions:
      - text: List the address book for contact {contactId}.
        slots:
          contactId: path.contactId
      - text: Show contact {contactId}'s saved addresses, {pageSize} per page.
        slots:
          contactId: path.contactId
          pageSize: query.pageSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/contacts/{contactId}/address-book'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an address to a contact's address book
      effect: write
      questions:
      - How do I save a new shipping address for a contact?
      - Can I make a newly added address the contact's default for shipping?
      instructions:
      - text: Add address {address} to contact {contactId}'s address book.
        slots:
          address: requestBody.address
          contactId: path.contactId
      - text: 'Save {address} for contact {contactId} and make it default shipping: {defaultShipping}.'
        slots:
          address: requestBody.address
          contactId: path.contactId
          defaultShipping: requestBody.defaultShipping
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/contacts/{contactId}/address-book/{addressBookEntryId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one saved address for a contact
      effect: read
      questions:
      - How do I look up one specific saved address for a contact?
      - Is a particular address book entry marked as the default shipping address?
      instructions:
      - text: Get address book entry {addressBookEntryId} for contact {contactId}.
        slots:
          addressBookEntryId: path.addressBookEntryId
          contactId: path.contactId
      - text: Show the saved address {addressBookEntryId} belonging to contact {contactId}.
        slots:
          addressBookEntryId: path.addressBookEntryId
          contactId: path.contactId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/contacts/{contactId}/address-book/{addressBookEntryId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a contact's saved address
      effect: write
      questions:
      - How do I correct a typo in a contact's existing saved address?
      - Why doesn't unsetting default shipping on the current default address take effect?
      instructions:
      - text: Replace address book entry {addressBookEntryId} of contact {contactId} with {address}.
        slots:
          addressBookEntryId: path.addressBookEntryId
          contactId: path.contactId
          address: requestBody.address
      - text: Make saved address {addressBookEntryId} the default shipping address for contact {contactId}, keeping {address}.
        slots:
          addressBookEntryId: path.addressBookEntryId
          contactId: path.contactId
          address: requestBody.address
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/contacts/{contactId}/address-book/{addressBookEntryId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a saved address from a contact
      effect: destructive
      questions:
      - How do I remove an old address from a contact's address book?
      - What happens to the default shipping address if I delete it?
      instructions:
      - text: Delete address book entry {addressBookEntryId} from contact {contactId}.
        slots:
          addressBookEntryId: path.addressBookEntryId
          contactId: path.contactId
      - text: Remove saved address {addressBookEntryId} for contact {contactId}.
        slots:
          addressBookEntryId: path.addressBookEntryId
          contactId: path.contactId
      method: generated
      generated: '2026-10-01'