@wix/agent-skills 1.23.0 → 1.25.0

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).

package/skills/wix-headless-fast/install/context.mjs

@@ -1,126 +0,0 @@
-// The site context of a project folder — the one place that says which site a call targets.
-//
-//   node <SKILL_ROOT>/install/context.mjs [--refresh] [--no-pull]     (prints one JSON object)
-//
-// Two identities live in a Wix project and are the same site almost always:
-//   deploy  — `wix.config.json` (`siteId`, `appId`): where `wix release` uploads. The CLI's business.
-//   content — `.env.local` (`WIX_CLIENT_ID`, what `wix env pull` writes): the app the SDK client
-//             runs as, on every stack (the Astro integration reads WIX_CLIENT_ID from the env and
-//             never the config; the other stacks get it copied into src/wix/config.ts by deploy.mjs).
-// They differ on a MIGRATION PREVIEW: a project whose config points at a fresh site created only to
-// host the deployment, while `.env.local` carries the credentials of the site being migrated (the
-// parent) and says so. Then every admin, discovery and seed call targets the parent, the SDK client
-// is the parent's, and only the release goes to the child. Completing the migration is a CLI step
-// that does not exist yet; this module only reads the state.
-//
-// `env pull` runs here when `.env.local` is missing (or --refresh): it is the source of the content
-// identity, and the Astro build refuses to run without it. Non-interactive (CI=1); a failure is
-// reported in `pullError` and the config's ids stand in, so a caller can still work offline.
-import { spawnSync } from "node:child_process";
-import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-// The variables `wix env pull` writes for a migration preview. The names are the platform's and are
-// spelled once, here.
-export const ENV = {
-  clientId: "WIX_CLIENT_ID",
-  parentSiteId: "WIX_MIGRATION_PARENT_SITE_ID",
-  migration: "WIX_MIGRATION",
-};
-
-/** KEY=value lines of a dotenv file, quotes stripped; null when the file is absent. */
-export function readEnvFile(file) {
-  if (!existsSync(file)) return null;
-  const out = {};
-  for (const raw of readFileSync(file, "utf8").split(/\r?\n/)) {
-    const line = raw.trim();
-    if (!line || line.startsWith("#")) continue;
-    const eq = line.indexOf("=");
-    if (eq === -1) continue;
-    const key = line.slice(0, eq).trim().replace(/^export\s+/, "");
-    let value = line.slice(eq + 1).trim();
-    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-      value = value.slice(1, -1).replace(/\\"/g, '"');
-    }
-    out[key] = value;
-  }
-  return out;
-}
-
-export function readWixConfig(cwd) {
-  const file = join(cwd, "wix.config.json");
-  if (!existsSync(file)) return null;
-  try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; }
-}
-
-const truthy = (v) => typeof v === "string" && /^(1|true|yes|on)$/i.test(v.trim());
-
-const ENV_PULL = ["-y", "@wix/cli@latest", "env", "pull"];
-const runPull = (dir) => spawnSync("npx", ENV_PULL, { cwd: dir, env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 180_000 });
-
-/**
- * `wix env pull` into `cwd/.env.local`. The CLI mounts `env` only once the folder reads as an Astro
- * project (an astro.config.* file, or `site.outputDirectory` in the config); a folder that holds just
- * the downloaded `wix.config.json` gets "unknown command 'env'". Then the pull runs in a temp folder
- * holding a copy of the config and an empty astro.config.mjs, and the `.env.local` comes back here.
- */
-export function pullEnv(cwd) {
-  const envFile = join(cwd, ".env.local");
-  let r = runPull(cwd);
-  if (r.status === 0 && existsSync(envFile)) return { ok: true, via: "in place" };
-  const notAProjectYet = /unknown command 'env'/.test(`${r.stderr}${r.stdout}`);
-  if (notAProjectYet) {
-    const tmp = mkdtempSync(join(tmpdir(), "wix-env-pull-"));
-    try {
-      copyFileSync(join(cwd, "wix.config.json"), join(tmp, "wix.config.json"));
-      writeFileSync(join(tmp, "astro.config.mjs"), "");
-      r = runPull(tmp);
-      if (r.status === 0 && existsSync(join(tmp, ".env.local"))) {
-        copyFileSync(join(tmp, ".env.local"), envFile);
-        return { ok: true, via: "stub project" };
-      }
-    } finally {
-      rmSync(tmp, { recursive: true, force: true });
-    }
-  }
-  return { ok: false, error: (r.stderr || r.stdout || "env pull produced no .env.local — is the Wix CLI logged in? (npx @wix/cli@latest whoami)").trim().slice(-400) };
-}
-
-/**
- * `{ deploy: { siteId, appId }, content: { siteId, clientId }, migration: { active, parentSiteId },
- *    env: { file, present, pulled }, pullError?, warnings: [] }`.
- * `pull`: "auto" (default) pulls when `.env.local` is missing; true always; false never.
- */
-export function siteContext({ cwd = process.cwd(), pull = "auto" } = {}) {
-  const config = readWixConfig(cwd) ?? {};
-  const deploy = { siteId: config.siteId ?? config.projectId ?? null, appId: config.appId ?? null };
-  const envFile = join(cwd, ".env.local");
-  let pulled = false, pullError;
-  if (deploy.siteId && (pull === true || (pull === "auto" && !existsSync(envFile)))) {
-    const r = pullEnv(cwd);
-    if (r.ok) pulled = r.via;
-    else pullError = r.error;
-  }
-  const env = readEnvFile(envFile) ?? {};
-  const parentSiteId = env[ENV.parentSiteId] || null;
-  const active = !!parentSiteId && (truthy(env[ENV.migration]) || env[ENV.migration] === undefined);
-  const migration = { active, parentSiteId: active ? parentSiteId : null };
-  const clientId = env[ENV.clientId] || deploy.appId;
-  const content = { siteId: active ? parentSiteId : deploy.siteId, clientId };
-  const warnings = [];
-  if (env[ENV.clientId] && deploy.appId && env[ENV.clientId] !== deploy.appId && !active) {
-    warnings.push(`.env.local ${ENV.clientId} differs from wix.config.json appId and no migration is declared — the SDK client runs as the env's app, the release goes to the config's site`);
-  }
-  if (active && migration.parentSiteId === deploy.siteId) {
-    warnings.push("the migration's parent site is the deploy site itself — nothing is being migrated");
-  }
-  return { deploy, content, migration, env: { file: envFile, present: Object.keys(env).length > 0, pulled }, ...(pullError ? { pullError } : {}), warnings };
-}
-
-// ---- CLI ----------------------------------------------------------------------------------------
-if (process.argv[1] && /context\.mjs$/.test(process.argv[1])) {
-  const argv = process.argv.slice(2);
-  const pull = argv.includes("--no-pull") ? false : argv.includes("--refresh") ? true : "auto";
-  console.log(JSON.stringify(siteContext({ pull }), null, 2));
-}

package/skills/wix-manage/references/cms/cms-data-operations-extended.md

@@ -1,263 +0,0 @@
----
-name: "CMS Data Operations Extended"
-description: Additional CMS data operations including count, upsert (bulk save), and update by filter patterns.
----
-# CMS Data Operations Extended
-
-This recipe covers additional CMS data operations not included in the basic CRUD recipe.
-
-## Prerequisites
-
-1. Wix CMS enabled on the site
-2. Collections created with data
-3. API access with CMS permissions
-
-## Required APIs
-
-- **Data Items API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/introduction)
-
-## Count Data Items
-
-Count items in a collection, optionally with filters.
-
-**Endpoint**: `POST /wix-data/v2/items/count`
-
-**Count All Items**:
-```bash
-curl -X POST \
-'https://www.wixapis.com/wix-data/v2/items/count' \
--H 'Content-Type: application/json' \
--H 'Authorization: <AUTH>' \
--d '{
-  "dataCollectionId": "Products"
-}'
-```
-
-**Response**:
-```json
-{
-  "totalCount": 42
-}
-```
-
-**Count with Filter**:
-```bash
-curl -X POST \
-'https://www.wixapis.com/wix-data/v2/items/count' \
--H 'Content-Type: application/json' \
--H 'Authorization: <AUTH>' \
--d '{
-  "dataCollectionId": "Products",
-  "filter": {
-    "inStock": true
-  }
-}'
-```
-
-**Count with Complex Filter**:
-```json
-{
-  "dataCollectionId": "Products",
-  "filter": {
-    "$and": [
-      { "inStock": true },
-      { "price": { "$gte": 50 } }
-    ]
-  }
-}
-```
-
-## Bulk Save (Upsert)
-
-Insert new items or update existing items in a single operation. This is useful for syncing data.
-
-**Endpoint**: `POST /wix-data/v2/bulk/items/save`
-
-**Request Body**:
-```json
-{
-  "dataCollectionId": "Products",
-  "dataItems": [
-    {
-      "id": "existing-item-id",
-      "data": {
-        "title": "Updated Product",
-        "price": 199.99,
-        "inStock": true
-      }
-    },
-    {
-      "data": {
-        "title": "New Product",
-        "price": 79.99,
-        "inStock": true
-      }
-    }
-  ],
-  "returnEntity": true
-}
-```
-
-### Bulk Save Behavior
-
-| Scenario | Action |
-|----------|--------|
-| No `id` provided | INSERT - Creates new item with generated ID |
-| `id` provided, doesn't exist | INSERT - Creates new item with provided ID |
-| `id` provided, exists | UPDATE - Replaces existing item |
-
-> **Warning**: When updating, the entire item is replaced. Include all fields you want to keep.
-
-## Update by Filter Pattern
-
-Wix CMS doesn't have a direct "update by filter" API. Use this two-step pattern:
-
-### 3.1: Query Items to Update
-
-```bash
-curl -X POST \
-'https://www.wixapis.com/wix-data/v2/items/query' \
--H 'Content-Type: application/json' \
--H 'Authorization: <AUTH>' \
--d '{
-  "dataCollectionId": "Products",
-  "query": {
-    "filter": {
-      "category": "electronics"
-    }
-  }
-}'
-```
-
-### 3.2: Bulk Update Those Items
-
-> **Important**: Use `id` (not `_id`) at the element level. The `data` object should NOT contain `_id`.
-
-```bash
-curl -X POST \
-'https://www.wixapis.com/wix-data/v2/bulk/items/update' \
--H 'Content-Type: application/json' \
--H 'Authorization: <AUTH>' \
--d '{
-  "dataCollectionId": "Products",
-  "dataItems": [
-    {
-      "id": "item-1-from-query",
-      "data": {
-        "title": "Updated Title 1",
-        "price": 99.99,
-        "onSale": true
-      }
-    },
-    {
-      "id": "item-2-from-query",
-      "data": {
-        "title": "Updated Title 2",
-        "price": 149.99,
-        "onSale": true
-      }
-    }
-  ]
-}'
-```
-
-### Alternative: Bulk Patch (Partial Update)
-
-If you only want to update specific fields without replacing the entire item, use Bulk Patch:
-
-**Endpoint**: `POST /wix-data/v2/bulk/items/patch`
-
-> **Important**: This endpoint uses `patches` array with `fieldModifications`, NOT `dataItems`. Do not confuse with bulk update.
-
-```bash
-curl -X POST \
-'https://www.wixapis.com/wix-data/v2/bulk/items/patch' \
--H 'Content-Type: application/json' \
--H 'Authorization: <AUTH>' \
--d '{
-  "dataCollectionId": "Products",
-  "patches": [
-    {
-      "dataItemId": "item-1",
-      "fieldModifications": [
-        {
-          "fieldPath": "onSale",
-          "action": "SET_FIELD",
-          "setFieldOptions": {
-            "value": true
-          }
-        }
-      ]
-    }
-  ]
-}'
-```
-
-> **Common error**: If you get `WDE0080: patches must not be empty`, you sent `dataItems` instead of `patches`. Use the format above.
-
-## Truncate Collection
-
-Remove all items from a collection (dangerous operation).
-
-**Endpoint**: `POST /wix-data/v2/items/truncate`
-
-```bash
-curl -X POST \
-'https://www.wixapis.com/wix-data/v2/items/truncate' \
--H 'Content-Type: application/json' \
--H 'Authorization: <AUTH>' \
--d '{
-  "dataCollectionId": "TestCollection"
-}'
-```
-
-> **Warning**: This permanently deletes ALL items in the collection. Use with extreme caution.
-
-## Aggregate Data
-
-Perform calculations on collection data using a pipeline of sequential stages.
-
-**Endpoint**: `POST /wix-data/v2/items/aggregate-pipeline`
-
-**Count by Category**:
-```bash
-curl -X POST \
-'https://www.wixapis.com/wix-data/v2/items/aggregate-pipeline' \
--H 'Content-Type: application/json' \
--H 'Authorization: <AUTH>' \
--d '{
-  "dataCollectionId": "Products",
-  "pipeline": {
-    "stages": [
-      {
-        "group": {
-          "groupIds": [
-            {"key": "category", "expression": {"fieldPath": "category"}}
-          ],
-          "accumulators": [
-            {
-              "resultFieldName": "count",
-              "sum": {"expression": {"numeric": 1}}
-            }
-          ]
-        }
-      }
-    ]
-  }
-}'
-```
-
-## Operation Comparison
-
-| Operation | Use Case | Behavior |
-|-----------|----------|----------|
-| **Bulk Insert** | Add new items only | Fails if ID exists |
-| **Bulk Update** | Update existing items | Fails if ID doesn't exist, replaces entire item |
-| **Bulk Save** | Upsert (insert or update) | Creates or updates based on ID |
-| **Bulk Patch** | Partial update | Only modifies specified fields |
-
-## Related Documentation
-
-- [Data Items API Reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/introduction)
-- [CMS Operations Best Practices](cms-data-items-crud.md)
-- [CMS Schema Management](cms-schema-management.md)

package/skills/wix-manage/references/cms/cms-references-and-relationships.md

@@ -1,162 +0,0 @@
----
-name: "CMS References And Relationships"
-description: "Add, replace, or remove items from MULTI_REFERENCE fields. Use insert-references, replace-references, remove-references endpoints. Required for managing multi-reference relationships - these CANNOT be set via regular insert/update/patch operations. Also covers single references and querying with expanded references."
----
-# CMS References & Relationships
-
-> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
-
-This recipe covers linking CMS collections together using reference fields.
-
-## Prerequisites
-
-1. Wix CMS enabled on the site
-2. At least two collections to link together
-3. API access with CMS permissions
-
-## Required APIs
-
-- **Collections API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/introduction)
-- **Data Items API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/introduction)
-
-## Reference Types
-
-| Type | Field Type | Relationship | Example |
-|------|------------|--------------|---------|
-| Single Reference | `REFERENCE` | One-to-one, Many-to-one | Product → Category |
-| Multi-Reference | `MULTI_REFERENCE` | One-to-many, Many-to-many | Product → Tags |
-
-## Add a Single Reference Field
-
-**Endpoint**: `POST /wix-data/v2/collections/create-field`
-
-```bash
-curl -X POST \
-'https://www.wixapis.com/wix-data/v2/collections/create-field' \
--H 'Content-Type: application/json' \
--H 'Authorization: <AUTH>' \
--d '{
-  "dataCollectionId": "Products",
-  "field": {
-    "key": "category",
-    "displayName": "Category",
-    "type": "REFERENCE",
-    "typeMetadata": {
-      "reference": {
-        "referencedCollectionId": "Categories"
-      }
-    }
-  }
-}'
-```
-
-## Add a Multi-Reference Field
-
-**Endpoint**: `POST /wix-data/v2/collections/create-field`
-
-```bash
-curl -X POST \
-'https://www.wixapis.com/wix-data/v2/collections/create-field' \
--H 'Content-Type: application/json' \
--H 'Authorization: <AUTH>' \
--d '{
-  "dataCollectionId": "Products",
-  "field": {
-    "key": "tags",
-    "displayName": "Tags",
-    "type": "MULTI_REFERENCE",
-    "typeMetadata": {
-      "multiReference": {
-        "referencedCollectionId": "Tags",
-        "referencingFieldKey": "products",
-        "referencingDisplayName": "Products"
-      }
-    }
-  }
-}'
-```
-
-## Insert Multi-Reference Links
-
-**Endpoint**: `POST /wix-data/v2/bulk/items/insert-references`
-
-```json
-{
-  "dataCollectionId": "Products",
-  "dataItemReferences": [
-    {
-      "referringItemId": "product-item-id",
-      "referringItemFieldName": "tags",
-      "referencedItemId": "tag-1-item-id"
-    },
-    {
-      "referringItemId": "product-item-id",
-      "referringItemFieldName": "tags",
-      "referencedItemId": "tag-2-item-id"
-    }
-  ],
-  "returnEntity": true
-}
-```
-
-## Replace All References
-
-**Endpoint**: `POST /wix-data/v2/items/replace-references`
-
-```json
-{
-  "dataCollectionId": "Products",
-  "referringItemId": "product-item-id",
-  "referringItemFieldName": "tags",
-  "newReferencedItemIds": ["new-tag-1-id", "new-tag-2-id", "new-tag-3-id"]
-}
-```
-
-> **Note**: To remove all references, pass an empty array for `newReferencedItemIds`.
-
-## Remove References (Bulk)
-
-**Endpoint**: `POST /wix-data/v2/bulk/items/remove-references`
-
-```json
-{
-  "dataCollectionId": "Products",
-  "dataItemReferences": [
-    {
-      "referringItemId": "product-id-1",
-      "referringItemFieldName": "tags",
-      "referencedItemId": "tag-to-remove-id"
-    }
-  ]
-}
-```
-
-## Query with Referenced Items Expanded
-
-**Endpoint**: `POST /wix-data/v2/items/query`
-
-```json
-{
-  "dataCollectionId": "Products",
-  "query": {
-    "filter": {
-      "inStock": true
-    }
-  },
-  "includeReferencedItems": ["category", "tags"]
-}
-```
-
-## Reference Query Operators
-
-| Operator | Description | Example |
-|----------|-------------|---------|
-| `$eq` | Exact match (single reference) | `{ "category": "id" }` |
-| `$hasSome` | Has at least one of | `{ "tags": { "$hasSome": ["id1", "id2"] } }` |
-| `$hasAll` | Has all of | `{ "tags": { "$hasAll": ["id1", "id2"] } }` |
-
-## Related Documentation
-
-- [Data Items API Reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/introduction)
-- [Collections API Reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/introduction)
-- [CMS Schema Management Recipe](cms-schema-management.md)