@vtex/faststore 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Every published version of `@vtex/faststore` has a section here. From `0.0.2` on, each one is
+written when its release pull request opens, and reviewed alongside the API delta that justifies the
+version.
+
+## 0.0.1
+
+Bootstrap release. It exists so that `@vtex/faststore` has a page on npmjs, which npm requires
+before a trusted publisher can be configured: `npm trust` refuses a package that is not already on
+the registry.
+
+Published by hand with a short-lived granular access token, outside the release pull request that
+gates every later version. The contents are the committed `0.0.1` tree, so the four snapshotted
+entries are what `etc/*.api.md` recorded at that commit. There is no baseline to diff against.
+
+The version line starts for real at `0.0.2`, the first release to pass through `release-checks.yml`
+and publish on a merge.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VTEX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @vtex/faststore
+
+The FastStore AI Native SDK: a component library built on [Base UI](https://base-ui.com), the authoring
+primitives that describe those components to a store compiler, and the typed GraphQL surface an API Extension
+declares its schema with.
+
+```bash
+npm install @vtex/faststore
+```
+
+## Pre-1.0
+
+The version line is `0.0.x`. Under semver every patch may break, and a caret range pins to one exact version.
+Nothing here is a compatibility promise yet: 138 types are reachable through the public entries without being
+named in them, and the authoring loop this SDK belongs to is not finished.
+
+This release makes the SDK installable and importable. It does not yet make an extension package buildable
+outside the FastStore repository — the catalog build runs through the `faststore` CLI, which is not published.
+
+## Entry points
+
+Four public subpaths, split by audience. Each has a committed type-surface snapshot, so a change to any of them
+lands as a reviewable diff before it ships.
+
+| Entry | For | Holds |
+| --- | --- | --- |
+| `@vtex/faststore` | authoring | `defineComponent`, `defineContentType`, `mockAction`, the contract types |
+| `@vtex/faststore/client` | store runtime | Apollo hooks, `useStorefrontContext`, `useStorefrontFormatters`, `gql` |
+| `@vtex/faststore/components` | store runtime | every particle and matter, plus `Session` |
+| `@vtex/faststore/graphql` | API Extension authoring | `defineSubgraph`, `gql`, the subgraph types |
+
+`@vtex/faststore/graphql` is a zero-import island: nothing in it reaches another entry, React, Next or Apollo,
+so an API Extension's server artifact never drags the component library in.
+
+Three further subpaths under `@vtex/faststore/internal/*` exist for generated code. They are outside the
+contract, carry no snapshot, and may change in any release.
+
+### The two `gql` exports
+
+`./graphql` and `./client` both export something called `gql`, and they are **not** interchangeable:
+
+| From | Returns | Does |
+| --- | --- | --- |
+| `@vtex/faststore/graphql` | `string` | nothing — an identity tag, so editors highlight the SDL literal |
+| `@vtex/faststore/client` | `DocumentNode` | parses the query and strips `loc` |
+
+Use the `./graphql` one for `defineSubgraph`'s `typeDefs`, which is a plain SDL string, and the `./client` one
+for anything you hand to an Apollo hook. Swapping them is a type error in both directions.
+
+## Data exports
+
+Four JSON documents and one stylesheet ship alongside the code, for tooling that reads the library rather than
+importing it:
+
+| Export | Holds |
+| --- | --- |
+| `@vtex/faststore/catalog.json` | every component's editor metadata and prop schema |
+| `@vtex/faststore/actions.json` | the declared actions |
+| `@vtex/faststore/content-types.json` | the declared content types |
+| `@vtex/faststore/message-locales.json` | the shipped message locales |
+| `@vtex/faststore/tailwind.css` | the Tailwind theme the components style against |
+
+These carry no snapshot. Treat their shape as unstable while the package is pre-1.0.
+
+## Peer dependencies
+
+All five are optional:
+
+| Peer | Range |
+| --- | --- |
+| `next` | `>=16` |
+| `react` | `^19.0.0` |
+| `react-dom` | `^19.0.0` |
+| `@apollo/client` | `^4.1.7` |
+| `@apollo/client-integration-nextjs` | `^0.14.5` |
+
+They are peers rather than dependencies so the app resolves one copy of each. Two copies of `@apollo/client`
+mean two caches, and the reactive state behind the hooks would split across them.
+
+They are optional because the entries are audience-split: an API Extension that only imports `./graphql` needs
+none of them. Install whatever your entries require.
+
+## Styling
+
+Every component renders `data-fs-*` attributes for particle identity and state targeting, and accepts a
+`className`. Styling comes from named swatches that resolve to Tailwind utility class strings at compile time,
+so the look of a store lives in its own configuration rather than in this package.
+
+## Platform support
+
+Pure JavaScript, types, CSS, and JSON. No native code, no platform, libc, or toolchain constraint.
+
+## License
+
+MIT. The full text ships in the package, as `LICENSE`.

package/dist/actions.json

@@ -0,0 +1,334 @@
+{
+  "cart": {
+    "namespace": "cart",
+    "description": "Mutation-backed writes against the current cart (consolidates useCartMutations / CartRoot).",
+    "provider": {
+      "name": "CartActionProvider",
+      "importPath": "@vtex/faststore/internal/client"
+    },
+    "methods": {
+      "addItem": {
+        "description": "Add an item to the cart (async strategy). Creates the cart on first add.",
+        "payload": [
+          {
+            "name": "variantId",
+            "type": "string"
+          },
+          {
+            "name": "seller",
+            "type": "string"
+          },
+          {
+            "name": "quantity",
+            "type": "number",
+            "optional": true
+          }
+        ]
+      },
+      "removeItem": {
+        "description": "Remove a line from the cart (optimistic strategy).",
+        "payload": [
+          {
+            "name": "id",
+            "type": "string"
+          }
+        ]
+      },
+      "removeItems": {
+        "description": "Remove several lines from the cart in one call (optimistic strategy).",
+        "payload": [
+          {
+            "name": "ids",
+            "type": "string[]"
+          }
+        ]
+      },
+      "increaseQuantity": {
+        "description": "Increase a line's quantity by N (default 1, optimistic strategy).",
+        "payload": [
+          {
+            "name": "id",
+            "type": "string"
+          },
+          {
+            "name": "by",
+            "type": "number",
+            "optional": true
+          }
+        ]
+      },
+      "decreaseQuantity": {
+        "description": "Decrease a line's quantity by N (default 1, optimistic). Removes the line at <= 0.",
+        "payload": [
+          {
+            "name": "id",
+            "type": "string"
+          },
+          {
+            "name": "by",
+            "type": "number",
+            "optional": true
+          }
+        ]
+      },
+      "applyCoupon": {
+        "description": "Apply a coupon code to the cart (async strategy). Server recomputes totals.",
+        "payload": [
+          {
+            "name": "code",
+            "type": "string"
+          }
+        ]
+      },
+      "removeCoupon": {
+        "description": "Remove a coupon code from the cart (async strategy). Server recomputes totals.",
+        "payload": [
+          {
+            "name": "code",
+            "type": "string"
+          }
+        ]
+      },
+      "validate": {
+        "description": "Re-check the active cart against the platform and adopt corrected availability (async, read-only upstream).",
+        "payload": []
+      }
+    }
+  },
+  "identity": {
+    "namespace": "identity",
+    "description": "Mutation-backed writes against the shopper identity entities (client profile, consent preferences, account profile).",
+    "provider": {
+      "name": "IdentityActionProvider",
+      "importPath": "@vtex/faststore/internal/client"
+    },
+    "methods": {
+      "clientProfileUpdate": {
+        "description": "Persist profile fields (partial) to the active cart (async strategy). Sending email flips Session.isIdentified.",
+        "payload": [
+          {
+            "name": "email",
+            "type": "string",
+            "optional": true
+          },
+          {
+            "name": "firstName",
+            "type": "string",
+            "optional": true
+          },
+          {
+            "name": "lastName",
+            "type": "string",
+            "optional": true
+          },
+          {
+            "name": "phone",
+            "type": "string",
+            "optional": true
+          },
+          {
+            "name": "document",
+            "type": "string",
+            "optional": true
+          }
+        ]
+      },
+      "clientPreferencesUpdate": {
+        "description": "Persist consent opt-in flags (partial) to the active cart (async strategy). Writes only the provided flag(s).",
+        "payload": [
+          {
+            "name": "optinNewsLetter",
+            "type": "boolean",
+            "optional": true
+          },
+          {
+            "name": "savePersonalData",
+            "type": "boolean",
+            "optional": true
+          }
+        ]
+      },
+      "customerProfileUpdate": {
+        "description": "Persist profile fields (partial) to the persistent account profile, not the cart (async strategy). Omitted fields are untouched; an empty string erases.",
+        "payload": [
+          {
+            "name": "firstName",
+            "type": "string",
+            "optional": true
+          },
+          {
+            "name": "lastName",
+            "type": "string",
+            "optional": true
+          },
+          {
+            "name": "homePhone",
+            "type": "string",
+            "optional": true
+          },
+          {
+            "name": "mobilePhone",
+            "type": "string",
+            "optional": true
+          },
+          {
+            "name": "document",
+            "type": "string",
+            "optional": true
+          },
+          {
+            "name": "documentType",
+            "type": "string",
+            "optional": true
+          },
+          {
+            "name": "birthDate",
+            "type": "string",
+            "optional": true
+          },
+          {
+            "name": "gender",
+            "type": "string",
+            "optional": true
+          }
+        ]
+      }
+    }
+  },
+  "region": {
+    "namespace": "region",
+    "description": "Mutation-backed writes against the shopper's active region (postal code).",
+    "provider": {
+      "name": "RegionActionProvider",
+      "importPath": "@vtex/faststore/internal/client"
+    },
+    "methods": {
+      "setPostalCode": {
+        "description": "Set the active region from a postal code, masked or bare (async/pessimistic). Resolves the payload errors.",
+        "payload": [
+          {
+            "name": "postalCode",
+            "type": "string"
+          }
+        ]
+      }
+    }
+  },
+  "session": {
+    "namespace": "session",
+    "description": "Mutation-backed authentication writes against the VTEX ID session (login, access code, logout).",
+    "provider": {
+      "name": "SessionActionProvider",
+      "importPath": "@vtex/faststore/internal/client"
+    },
+    "methods": {
+      "loginWithPassword": {
+        "description": "Sign in with email and password (async/pessimistic). Resolves the payload userErrors.",
+        "payload": [
+          {
+            "name": "email",
+            "type": "string"
+          },
+          {
+            "name": "password",
+            "type": "string"
+          }
+        ]
+      },
+      "requestAccessCode": {
+        "description": "Email the shopper an access code; resolves the opaque authenticationToken to round-trip.",
+        "payload": [
+          {
+            "name": "email",
+            "type": "string"
+          }
+        ]
+      },
+      "validateAccessCode": {
+        "description": "Validate an access code with its authenticationToken (async/pessimistic); logs the shopper in.",
+        "payload": [
+          {
+            "name": "email",
+            "type": "string"
+          },
+          {
+            "name": "accessCode",
+            "type": "string"
+          },
+          {
+            "name": "authenticationToken",
+            "type": "string"
+          }
+        ]
+      },
+      "logout": {
+        "description": "Sign out, clearing the auth cookies (async/pessimistic). Idempotent for guests.",
+        "payload": []
+      }
+    }
+  },
+  "shipping": {
+    "namespace": "shipping",
+    "description": "Mutation-backed delivery writes against the VTEX orderForm shippingData (address in T2; option in T3).",
+    "provider": {
+      "name": "ShippingActionProvider",
+      "importPath": "@vtex/faststore/internal/client"
+    },
+    "methods": {
+      "setAddress": {
+        "description": "Persist the single delivery address in one submit (async/pessimistic). Resolves the payload userErrors.",
+        "payload": [
+          {
+            "name": "savedAddressId",
+            "type": "string"
+          },
+          {
+            "name": "recipientName",
+            "type": "string"
+          },
+          {
+            "name": "postalCode",
+            "type": "string"
+          },
+          {
+            "name": "country",
+            "type": "string"
+          },
+          {
+            "name": "street",
+            "type": "string"
+          },
+          {
+            "name": "number",
+            "type": "string"
+          },
+          {
+            "name": "complement",
+            "type": "string"
+          },
+          {
+            "name": "neighborhood",
+            "type": "string"
+          },
+          {
+            "name": "city",
+            "type": "string"
+          },
+          {
+            "name": "state",
+            "type": "string"
+          }
+        ]
+      },
+      "selectOption": {
+        "description": "Select a delivery option for the whole cart (async/pessimistic). Resolves the payload userErrors.",
+        "payload": [
+          {
+            "name": "optionId",
+            "type": "string"
+          }
+        ]
+      }
+    }
+  }
+}