@wix/agent-skills 1.22.0 → 1.24.0

package/skills/wix-manage/references/cms/cms-schema-management.md

@@ -37,7 +37,7 @@ curl -X GET \
 
 ## Get Collection Schema
 
-**Endpoint**: `GET /wix-data/v2/collections/{collectionId}`
+**Endpoint**: `GET https://www.wixapis.com/wix-data/v2/collections/{collectionId}`
 
 ```bash
 curl -X GET \
@@ -47,7 +47,7 @@ curl -X GET \
 
 ## Create a New Collection
 
-**Endpoint**: `POST /wix-data/v2/collections`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/collections`
 
 ```json
 {
@@ -72,7 +72,7 @@ curl -X GET \
 
 ## Add a Field to Existing Collection
 
-**Endpoint**: `POST /wix-data/v2/collections/create-field`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/collections/create-field`
 
 ```json
 {
@@ -90,7 +90,7 @@ curl -X GET \
 
 > **Warning**: This permanently deletes all data stored in this field across all items.
 
-**Endpoint**: `POST /wix-data/v2/collections/delete-field`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/collections/delete-field`
 
 ```json
 {
@@ -101,7 +101,7 @@ curl -X GET \
 
 ## Update Collection Settings
 
-**Endpoint**: `PATCH /wix-data/v2/collections/{collectionId}`
+**Endpoint**: `PATCH https://www.wixapis.com/wix-data/v2/collections/{collectionId}`
 
 ```json
 {
@@ -116,7 +116,7 @@ This works for `displayName`/`displayField`. **Permission updates currently fail
 
 **To change permissions on an existing collection, use the full-replace endpoint instead** (`UpdateDataCollection`, not `PatchDataCollection`) — it requires the collection's current `revision` and full `fields` array (get both from a `GET` first), but it does work:
 
-**Endpoint**: `PUT /wix-data/v2/collections`
+**Endpoint**: `PUT https://www.wixapis.com/wix-data/v2/collections`
 
 ```json
 {

package/skills/wix-manage/references/contacts/bulk-label-and-unlabel-contacts.md

@@ -1,12 +1,29 @@
 ---
 name: "Bulk Label and Unlabel Contacts"
-description: Adds/removes labels from multiple contacts using Contacts API bulk operations. Covers label creation, contact filtering, batch processing, and rate limit handling.
+description: Creates contact label definitions or adds/removes labels from matching contacts. Use Find or Create Label for label creation alone; use bulk labeling only when the user requests contact assignments.
 ---
 # Bulk Label And Unlabel Contacts
 
 ## Description
 Adds and removes labels from multiple contacts using the Wix Contacts REST API.
 
+## Create labels or assign labels?
+
+If the user asks to **create a label** (for example, "Create VIP, Wholesale, and Newsletter labels"), use [Find or Create Label](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/labels/find-or-create-label) directly. Creating a label definition does not require finding contacts or starting a bulk labeling job.
+
+```http
+POST https://www.wixapis.com/contacts/v4/labels
+Content-Type: application/json
+
+{"displayName":"VIP"}
+```
+
+Use the returned `label` and its `key`; `newLabel` distinguishes a newly created label from an existing one. For several names, make one call per name and check each result. Stop here when the request is only to create labels: do not assign them to contacts.
+
+If the user asks to **label or unlabel contacts**, resolve the requested label keys first, then follow the bulk assignment flow below. Create a missing label only when that is part of the authorized request. An explicit request to create labels or apply them to a specified set of contacts authorizes that operation; otherwise confirm the target and intended change before mutating.
+
+## Bulk assignment flow
+
 Labels are added to and removed from all contacts that meet the specified `filter` and `search` criteria.
 The request should specify a `filter` value, a `search` value, or both.
 To perform a dry run, call [Query Contacts](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/contact-v4/query-contacts) with the intended filter options.
@@ -17,6 +34,22 @@ The job's status can be retrieved with [Get Bulk Job](https://dev.wix.com/docs/a
 
 **IMPORTANT NOTE:** When specific contacts are to be labeled, they should be filtered by id.
 
+### Steps
+
+1. **Resolve label keys.** When adding, Find or Create Label (above) returns the `key`. To remove a label, or to
+   use only a label that already exists, look it up by name instead of creating it:
+   `POST https://www.wixapis.com/contacts/v4/labels/query` with
+   `{"query":{"filter":{"displayName":{"$eq":"Newsletter"}}}}`, and take each returned label's `key`.
+2. **Resolve named contacts to IDs** with Search Contacts, as in
+   [Update a Contact](update-a-contact.md) — Query Contacts cannot filter on a name:
+   `POST https://www.wixapis.com/contacts/v5/contacts/search` with `{"search":{"search":{"expression":"Leo Marsh"}}}`.
+   Each result in `contacts` has an `id` and `name.first` / `name.last`; keep only exact name matches. If none or
+   more than one contact matches, stop and ask the user.
+3. **Start the job** with the endpoint below, filtering by the resolved IDs:
+   `{"filter":{"id":{"$in":["<CONTACT_ID>"]}},"labelKeysToAdd":["<LABEL_KEY>"]}` (or `labelKeysToRemove`).
+4. **Confirm the job finished** with `GET https://www.wixapis.com/contacts/v4/bulk/jobs/{jobId}`; repeat until
+   `job.status` is `COMPLETED`, then report `job.successTotal` and `job.failedTotal`.
+
 ## API Endpoint
 `POST https://www.wixapis.com/contacts/v4/bulk/contacts/add-remove-labels`
 
@@ -29,10 +62,10 @@ curl -X POST \
   -H 'Content-Type: application/json' \
   -d '{
     "filter": {
-      "info.name.first": "John"
+      "id": { "$in": ["<CONTACT_ID_1>", "<CONTACT_ID_2>"] }
     },
-    "labelKeysToAdd": ["custom.name-john", "custom.name-starts-with-J"],
-    "labelKeysToRemove": ["custom.last-name-smith"]
+    "labelKeysToAdd": ["custom.newsletter"],
+    "labelKeysToRemove": ["custom.prospect"]
   }'
 ```
 

package/skills/wix-manage/references/ecommerce/ecom-pricing.md

@@ -1,6 +1,6 @@
 ---
 name: "Pricing & Promotions"
-description: Pricing & Promotions boundary owner — discounts, coupons, sales, ribbons, bundles. **Always load this dispatcher first when a question touches both discount work and refunds, payments, product-price edits, or shipping rates** — the rules for which side owns each topic live in this file, not in this README line.
+description: Routes discounts, coupons, sales and bundles to promotion recipes, and visual product ribbons to the Catalog Ribbons API. Load this dispatcher for mixed pricing/refund/payment/product-price/shipping requests to choose the appropriate APIs.
 ---
 
 # Pricing & Promotions
@@ -14,7 +14,9 @@ Discount rules, coupon codes, sales, ribbons, bundles, tiered pricing, and the s
 - A standing $0 shipping option/region rate → see **Shipping & fulfillment**.
 - Refunding a previous discounted order → route to verified Get Paid/payment docs or Dashboard guidance.
 
-> **Before dispatching** — confirm MerchantContext is loaded. If `siteData.country` is not in your conversation context, load it via [Load Merchant Context](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/e-commerce-load-context). Skip if already loaded.
+> **Ribbon-only requests** — go directly to the ribbon path below; skip MerchantContext and promotion-strategy discovery.
+>
+> **Before dispatching promotion requests** — confirm MerchantContext is loaded. If `siteData.country` is not in your conversation context, load it via [Load Merchant Context](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/e-commerce-load-context). Skip if already loaded.
 >
 > **Promotion dispatch.** Score each entry below by (a) the merchant's query → `intent:*` tags, (b) MerchantContext → context tags. Load the **highest-scoring** entry. Ties → highest `priority`. No match → follow the base recipe at the bottom.
 >
@@ -24,9 +26,33 @@ Discount rules, coupon codes, sales, ribbons, bundles, tiered pricing, and the s
 
 > - [Create coupon](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-coupon) — tags: `[intent:create-coupon]` · priority 0
 > - [Create discount rule (auto-apply)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) — tags: `[intent:create-discount-rule]` · priority 0
-> - [Add sale ribbon / new ribbon](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) — tags: `[intent:add-ribbon]` · priority 0 · *ribbons are configured via Discount Rules; same recipe*
+> - [Create or reuse a Catalog V3 ribbon](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/ribbons-v3/get-or-create-ribbon) — tags: `[intent:add-ribbon]` · priority 0 · *a ribbon is a visual product label, not a discount rule; follow the ribbon path below*
 > - [Schedule a future sale](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) — tags: `[intent:schedule-sale]` · priority 0 · *uses Discount Rules with `startTime` in the future*
 
+### Ribbon path
+
+For a Catalog V3 request such as "Create a Bestseller ribbon", use the idempotent name-based [Get or Create Ribbon](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/ribbons-v3/get-or-create-ribbon) method:
+
+```http
+POST https://www.wixapis.com/stores/v3/ribbons/get-or-create
+Content-Type: application/json
+
+{"ribbonName":"Bestseller"}
+```
+
+Read the returned `ribbon.id`. If the user requested only the ribbon definition, report that result and stop. If they also requested assignment to a product, read the product's current `revision` with `GET https://www.wixapis.com/stores/v3/products/{productId}`, as in [Update Product with Options](../stores/update-product-with-options.md). Then send only the ribbon with that `revision` through [Update Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/update-product); fields you omit are left unchanged:
+
+```http
+PATCH https://www.wixapis.com/stores/v3/products/{productId}
+Content-Type: application/json
+
+{"product":{"id":"<PRODUCT_ID>","revision":"<CURRENT_REVISION>","ribbon":{"id":"<RIBBON_ID>"}}}
+```
+
+This path covers Catalog V3.
+
+Do not create a coupon, discount rule, or price change just because a ribbon says "Sale". Those require a separate discount request. An explicit ribbon creation or assignment request authorizes that operation; otherwise confirm the intended change first. Merchant context needed for promotion recommendations is not a prerequisite to creating a named visual ribbon.
+
 ### Business flows — the orchestrator
 
 The single business-flow orchestrator (`recommend-ecommerce-strategy`) handles all strategic discount intents. It classifies internally (SEASONAL / UPSELL_BOOST / STOCK_MOVER / BUNDLE_AND_SAVE / ABANDONED_CART) and loads its `goal-*` / `flow-*` support files from the kept ecommerce-root siblings.

package/skills/wix-manage/references/sites/query-sites.md

@@ -6,7 +6,7 @@ description: List, count, and find the sites in a Wix account. Covers the namesp
 
 List, count, and find the sites in a Wix account.
 
-- **Auth**: account-level (a Wix user token, or an account-level API key). `wix token` prints one.
+- **Auth**: account-level (a Wix user token, or an account-level API key).
 - **Permission**: `SITE_LIST.READ` (scope `SCOPE.ACC-DC-OS.READ-SITE`).
 - **Endpoints**: list `POST https://www.wixapis.com/site-list/v2/sites/query` · count
   `POST https://www.wixapis.com/site-list/v2/sites/count`.
@@ -99,10 +99,3 @@ interface Site {
   parentChildRole: string;    // e.g. NONE
 }
 ```
-
-## Next Steps
-
-Use a site's `id` for site-level API calls — derive a site token from the account token
-(`wix token --site <id>`, or the `oauth2/token` refresh-grant in wix-auth `device-flow`), then read
-its context via [Read Site Context](read-site-context.md) or create sites with
-[Create Site from Template](create-site-from-template.md).

package/skills/wix-manage/references/sites/site-import.md

@@ -1,6 +1,6 @@
 ---
 name: "Site Import"
-description: Drive the Wix Site Import agent to migrate an existing store or site from another platform (Shopify, WooCommerce, Magento, or any URL) into Wix, or to import from CSV/TSV export files with no source site. Use this skill whenever the user wants to import, migrate, or clone a store/site into Wix, mentions moving off Shopify/WooCommerce/Magento, or gives a source store URL and asks to bring it into Wix. Covers starting the import, polling progress, answering the agent's mid-import questions, handling deploy/failure/auth-expiry states, and sending post-deploy follow-up changes.
+description: Drive the Wix Site Import agent to migrate an existing store or site from another platform (Shopify, WooCommerce, Magento, or any URL) into Wix — as a brand-new site or into the user's existing one — or to import from CSV/TSV export files with no source site. Use this skill whenever the user wants to import, migrate, or clone a store/site into Wix, mentions moving off Shopify/WooCommerce/Magento, or gives a source store URL and asks to bring it into Wix. Covers starting the import, polling progress, answering the agent's mid-import questions, handling deploy/failure/auth-expiry states, and sending post-deploy follow-up changes.
 ---
 
 # Site Import
@@ -24,8 +24,7 @@ and report the final result.
 5. **This API is the only site-creation tool for this task** — never
    substitute other Wix site-builder tools (see Scope).
 
-Base URL: `https://www.wixapis.com/site-import`. All calls use account-level
-scope on the signed-in Wix user's account. A full import typically takes
+Base URL: `https://www.wixapis.com/site-import`. A full import typically takes
 15–60 minutes.
 
 ## Calling the API
@@ -46,11 +45,12 @@ nothing useful.
 page, or any client-side code — those fail with CORS. The entire experience
 is plain chat — API calls plus short messages.
 
-Use the Wix account-level REST API tool available in your environment with
-the **full URL**. Start, Send-a-message, and Cancel are mutating (POST);
-Poll is read-only (GET).
+Use the Wix REST API tool available in your environment with the **full
+URL** (account-level, or site-scoped with a target `siteId` — see Start
+below for when each applies). Start, Send-a-message, and Cancel are mutating
+(POST); Poll is read-only (GET).
 
-Example — Start:
+Example — Start, account-level (creates a new site):
 
 ```
 POST https://www.wixapis.com/site-import/v1/imports
@@ -60,6 +60,19 @@ Body: {
 }
 ```
 
+Example — Start, site-scoped (imports into the user's existing site — same
+body, plus a `wix-site-id` header naming the destination site; see the
+Destination note under Start below):
+
+```
+POST https://www.wixapis.com/site-import/v1/imports
+Headers: { "wix-site-id": "<destination siteId>" }
+Body: {
+  "request": "Import https://example-store.com into my site",
+  "source_url": "https://example-store.com"
+}
+```
+
 Example — Start from exported files (no source site, FILE run):
 
 ```
@@ -96,11 +109,10 @@ API. Never fall back to other site-building tools (site-builder/template/AI
 site-generation tools) to "compensate" — not when the import is slow, and
 especially not when it FAILS.
 
-**Status comes ONLY from this API's Poll endpoint.** Never call
-`WixSiteBuilder`, `CreateSiteFromTemplate`, `pullSiteCreationJob`, or any
-other connector tool to "check on the build" — `WixSiteBuilder` in particular
-STARTS a new site build on every call, even when the prompt asks for status.
-A failed import ends with a clear failure report and a full stop; the user
+**Status comes ONLY from this API's Poll endpoint.** Never call another
+site-building or site-creation capability to "check on the build" — some
+such tools start a new site build on every call, even when asked only for
+status. A failed import ends with a clear failure report and a full stop; the user
 must never discover a different site in their account that they didn't ask
 for. If an alternative makes sense, propose it AFTER reporting the failure
 and act only on the user's explicit yes.
@@ -112,6 +124,17 @@ calling **Start**, confirm:
 - The source URL and platform are correct — or, for a file-only import, the
   export file URL(s) are correct
 - The user understands it runs for up to ~60 minutes and may ask questions mid-way
+- Which destination they want: a brand-new site, or their existing site by id
+  (site-scoped) — this can't be changed once Start is called. Importing into
+  an existing site writes into it directly and can add or overwrite its
+  current pages and content, so make sure they understand that before you
+  proceed — it isn't a safe side-by-side preview.
+  **If they want their existing site but haven't given a `siteId`, resolve
+  it yourself first** — from the account/site context already available to
+  you, or by querying the account's sites (see the Query Sites skill) — and
+  ask the user to pick when more than one candidate matches what they
+  described. Never guess a `siteId` or silently default to an account-level
+  call just because none was supplied.
 
 Also confirm before calling **Cancel** — it's irreversible.
 
@@ -183,14 +206,34 @@ You are the user experience; the API is plumbing. Keep the protocol invisible:
      `request`, and no `fileUrls`, is rejected with `SITE_UNIDENTIFIED`.
    Returns: `importId`, `sourcePlatform`, `sourceConfidence`, `destinationSiteId`.
    `sourcePlatform` comes back as `CSV` for a FILE run (no site was probed, so
-   `sourceConfidence` is meaningless there). `destinationSiteId` is the id of
-   the Wix site being imported into — returned as soon as Start succeeds,
-   even before a source is confirmed.
-   **One import per store at a time, keyed on `source_url`** (or the file set
-   when there's no `source_url`): re-starting with the same identity continues
-   the SAME migration (server returns the existing `importId`, no new import
-   created). A different identity always starts an independent migration, even
-   for the same user. If a different user on the account already owns an
+   `sourceConfidence` is meaningless there).
+   **Destination (new site vs. an existing site) is decided by call scope, not
+   a body field:** account-level (no site context) always creates a brand-new
+   site — the default when the user has none yet or wants a fresh one;
+   site-scoped (adding a `wix-site-id: <siteId>` header, same body — see the
+   examples above) writes into that existing site instead. Ask the user which
+   they want before calling Start — it can't change afterward. Get this
+   wrong at Start and you'll silently create an unwanted second site instead
+   of writing into the one they meant. Once Start has scoped the import,
+   keep sending that same `wix-site-id` header on every later call for that
+   `importId` (Poll, Send-a-message, Cancel included) — it won't create
+   another site at this point, but omitting it will fail authorization
+   against the site-scoped import. `destinationSiteId` in the
+   response echoes this (empty = new site, set = that existing site), returned
+   as soon as Start succeeds, even before a source is confirmed.
+   **One import per store at a time, keyed on `source_url` (or the file set
+   when there's no `source_url`) together with call scope** — account-level
+   and a given `wix-site-id` are different keys even for the identical
+   `source_url`/file set: re-starting with the same identity (same source
+   AND same scope) continues the SAME migration (server returns the
+   existing `importId`, no new import created). A different identity —
+   a different source, a different file set, or the same source at a
+   *different* call scope — always starts an independent migration, even
+   for the same user. This is why getting the scope wrong at Start matters
+   (see above): re-calling Start with the corrected scope does not fix the
+   original import, it starts a second, independent one. To redo a
+   mis-scoped import, **Cancel it first**, then Start again with the
+   correct scope. If a different user on the account already owns an
    import for that identity, Start returns
    `409 { "code": "IMPORT_IN_PROGRESS" }` — tell the user and stop.
 
@@ -238,7 +281,9 @@ You are the user experience; the API is plumbing. Keep the protocol invisible:
   - `FAILED` — terminal. Relay `message` in plain words.
   - `AUTH_EXPIRED` — recoverable, NOT success, nothing is live (golden rule 1).
     Tell the user the connection to their account expired and you're restarting,
-    then call Start again with the same request — work so far is preserved.
+    then call Start again with the same request, using the same call scope
+    (account-level, or the same `wix-site-id`) as the original Start — work so
+    far is preserved.
   - `CANCELLED` — terminal.
 - **Anything the user says mid-import goes straight to Send-a-message** — no
   need to wait for `NEEDS_INPUT`.
@@ -269,26 +314,45 @@ the user has no way to open a file.
 - Never invent a `deployUrl` — only report the one returned with `DEPLOYED`.
 - Treat `NEEDS_INPUT` and `AUTH_EXPIRED` as normal conversation turns, not
   errors.
-- **Site Import is in limited rollout, with no self-service enablement path.**
-  If Start returns `404` or `403` with `"code": "NOT_ENABLED"`, tell the user
-  plainly that site import isn't available on their account yet — then stop.
+- **Site Import is in closed beta, with no self-service enablement path.**
+  A `"code": "NOT_ENABLED"` on a `401`, `403`, or `404` from Start always means this
+  account isn't in the beta — whether the call was account-level or
+  site-scoped. The code isn't always present on an **account-level** call:
+  a not-yet-enrolled account's Start has been observed to come back as a
+  plain `401`/`403` (`{"message": "The caller is not permitted to perform this
+  action."}`, no code) as well as a plain `404` — treat any of those shapes there
+  as the beta-lockout case too. Don't probe other endpoints to diagnose it,
+  don't retry, and **don't create a site through any other site-building
+  capability to compensate — creating a site through a different path is
+  not a workaround here, it's the specific mistake this rule exists to
+  prevent.** Tell the user plainly and warmly that Site Import is
+  currently in a closed beta, that you'd be happy to help once they're
+  in, and that they can request access by filling out this short form:
+  https://forms.gle/RfZqVRtGCsPv7U7M6 — the team will follow up. Then
+  stop, having created nothing.
   **Do not tell them to "contact Wix support"**: this API is unlisted and
   ALPHA, Wix Support has no visibility into it or way to grant access, and the
   public "importing a site created outside of Wix" help-center article is an
   unrelated, long-stalled feature-request page — sending a user to either is a
-  dead end. If a Wix feedback tool is available in your environment, you may
-  offer to send feedback noting their interest; that is the only channel that
-  reaches the team. Do not retry or fall back to another site-creation tool.
-- Any other `403` on Start means the caller is not authorized — tell the user
-  and stop. Do not probe other endpoints to diagnose this. A `400` means a
-  required field is missing (`request`/`message` must be 1–20000 chars),
-  `source_url` exceeds 2048 chars, or `fileUrls` has more than 20 entries or
-  one over 2048 chars. A request with no identifiable site (no `source_url`
-  and no URL in `request`) and no `fileUrls` is rejected with
-  `SITE_UNIDENTIFIED` — ask the user for the store URL or export file(s) and
-  retry. A `fileUrls` entry that isn't a reachable http/https URL rejects the
-  whole call with `INVALID_FILE_URL` — tell the user which link failed and ask
-  for a working one.
+  dead end. The form above is the only channel that reaches the team.
+  **A `401`, `403`, or `404` on a site-scoped call *without* `"code": "NOT_ENABLED"`
+  is different** — it means the caller isn't authorized for that `siteId`
+  (wrong id, wrong account, no access), not a beta-enrollment issue. Tell
+  the user the destination site isn't accessible with their current
+  connection and stop; don't send them to the beta form for this.
+- For any other unrecognized error or exception on Start — a transient server
+  error, a timeout, a rate limit, or anything that isn't the closed-beta case
+  above or one of the specific cases below — don't guess that it's a
+  beta-enrollment issue and don't retry silently. Tell the user the import
+  couldn't be started, share what went wrong in plain language, and stop.
+- A `400` on Start means a required field is missing (`request`/`message`
+  must be 1–20000 chars), `source_url` exceeds 2048 chars, or `fileUrls` has
+  more than 20 entries or one over 2048 chars. A request with no identifiable
+  site (no `source_url` and no URL in `request`) and no `fileUrls` is rejected
+  with `SITE_UNIDENTIFIED` — ask the user for the store URL or export file(s)
+  and retry. A `fileUrls` entry that isn't a reachable http/https URL rejects
+  the whole call with `INVALID_FILE_URL` — tell the user which link failed and
+  ask for a working one.
 - Requesting an unknown id in `artifactIds` is silently ignored — not an error.
   A document simply may not exist yet on an earlier turn.
 - **The user cannot open files.** If a message mentions a document by filename,

package/skills/wix-auth/SKILL.md

@@ -1,12 +0,0 @@
----
-name: wix-auth
-description: "Authenticate with Wix to obtain an access token for calling Wix APIs. Use when an agent needs a valid Wix access token and has none, or when the stored token is expired."
----
-
-# Wix Auth
-
-Wix supports multiple authentication flows. This skill currently covers:
-
-- [Device Flow](references/device-flow.md) — interactive login via browser, no client secret required. Use when the agent is acting on behalf of a logged-in Wix user.
-
-Other flows (OAuth authorization code, API key) are documented at [https://www.wix.com/skills/docs](https://www.wix.com/skills/docs).

package/skills/wix-auth/references/device-flow.md

@@ -1,140 +0,0 @@
-# Device Flow
-
-Implements the OAuth 2.0 Device Authorization Grant (RFC 8628). The user approves in a browser while the agent polls for tokens.
-
-Produces two kinds of token:
-- **Account token** — works for account-level APIs (e.g. list sites). Expires in ~4 hours.
-- **Site token** — required for any site-specific API (contacts, products, bookings, …). Derived on demand from the account `refreshToken` + a `siteId`. Expires in ~15 minutes.
-
-## Constants
-
-```
-BASE_URL  = https://manage.wix.com
-CLIENT_ID = 6f95cec8-3e98-48b9-b4e5-1fb92fcd9973
-```
-
-Required headers on every request:
-
-```
-X-XSRF-TOKEN: nocheck
-Cookie: XSRF-TOKEN=nocheck
-User-Agent: wix-cli
-Content-Type: application/json   (on POST requests)
-```
-
-## Step 1 — Request a device code
-
-```
-GET /oauth2/device/code?clientId=CLIENT_ID
-```
-
-Response:
-
-```json
-{ "deviceCode": "…", "userCode": "XXXXXXXX", "verificationUri": "https://users.wix.com/login/device-login", "expiresIn": 600 }
-```
-
-## Step 2 — Ask the user to authorize
-
-Show the user this URL and code:
-
-```
-URL:  {verificationUri}?color=developer&studio=true
-Code: {userCode}
-```
-
-Make sure the user has copied or noted the code **before** opening the link — they'll need to enter it on the page. Present the URL as a clickable link that opens in a new tab if your interface supports it.
-
-## Step 3 — Poll for the token
-
-Every 3 seconds, POST:
-
-```
-POST /oauth2/token
-{ "clientId": "CLIENT_ID", "grantType": "urn:ietf:params:oauth:grant-type:device_code", "scope": "offline_access", "deviceCode": "{deviceCode}" }
-```
-
-- While waiting: server returns `400` with `{ "error": "authorization_pending" }` or `{ "message": "Device code is not yet verified" }` — keep polling.
-- On approval: `200` with `{ "access_token": "…", "refresh_token": "…", "expires_in": 14400 }`.
-- Stop polling after `expiresIn` seconds total.
-
-## Step 4 — Fetch user info
-
-```
-GET /_serverless/wix-cli-userinfo/userinfo
-Authorization: Bearer {access_token}
-```
-
-Response: `{ "userId": "…", "email": "…" }`
-
-## Step 5 — Persist
-
-At this point you already hold all the values in memory — store them securely to whatever credential store your platform provides (file, secrets manager, environment variables, etc.), without asking the user to enter them manually. **Treat these as secrets: never print them in the conversation, never include them in logs, and never send them to any service other than the Wix APIs.**
-
-```
-accessToken   string
-refreshToken  string
-expiresIn     number  (seconds)
-issuedAt      number  (Unix timestamp in seconds, recorded at the moment tokens were received)
-userInfo      { userId, email }
-```
-
-## Getting a valid token on subsequent calls
-
-**Account token**
-
-1. Load stored credentials. If missing → run the device flow above.
-2. Check validity: `issuedAt + expiresIn - 600 > now` (10-min buffer).
-3. If expired → refresh silently:
-
-```
-POST /oauth2/token
-{ "clientId": "CLIENT_ID", "grantType": "refresh_token", "refreshToken": "{refreshToken}" }
-```
-
-Same response shape as Step 3. Persist the new tokens with a fresh `issuedAt`.
-
-4. If refresh returns `400 invalid_grant` → session revoked; run the device flow again.
-
-**Site token**
-
-The account token returns `403` on site-level endpoints. Derive a site token on demand:
-
-```
-POST /oauth2/token
-{ "clientId": "CLIENT_ID", "grantType": "refresh_token", "refreshToken": "{refreshToken}", "siteId": "{siteId}" }
-```
-
-Response: `{ "access_token": "…", "refresh_token": "…", "expires_in": 900 }`
-
-Re-derive on each use rather than caching — it expires in 15 minutes.
-
-## Examples
-
-**List sites (account token)**
-
-```
-POST https://www.wixapis.com/site-list/v2/sites/query
-Authorization: Bearer {accountToken}
-{ "query": { "filter": { "namespace": { "$in": ["WIX", "HEADLESS"] } }, "cursorPaging": { "limit": 100 } } }
-```
-
-Returns `{ sites: [{ id, displayName, namespace, … }] }` — the `id` is the `siteId` for site-scoped calls.
-
-> Without the `namespace` filter, headless sites are silently excluded from results.
-
-**List contacts (site token)**
-
-```
-POST https://www.wixapis.com/contacts/v4/contacts/query
-Authorization: Bearer {siteToken}
-{ "query": { "paging": { "limit": 10 } } }
-```
-
-Returns `{ contacts: […] }`.
-
----
-
-For the full Wix REST API reference — endpoints, request/response shapes, and field details — see [https://www.wix.com/skills/docs](https://www.wix.com/skills/docs).
-
-For REST API recipes covering common management operations (stores, bookings, contacts, CMS, and more) — see [https://www.wix.com/skills/manage](https://www.wix.com/skills/manage).