@lessly/sdk-app 0.3.0 → 0.3.1

package/README.md

@@ -4,6 +4,8 @@ The Lessly SDK for App is a TypeScript SDK that provides runtime bindings and ty
 
 **Note:** The `src/gen` directory contains generated SDK code and should not be edited by hand. Generated files are produced by running `npm run generate` with an API catalog.
 
+The committed `src/gen` is a **convenience snapshot** — it lets the repo type-check, test, and build offline. It is **not** the source of truth: canonical generation happens **at publish time**, when Cloud Build regenerates `src/gen` from the live catalog before publishing. The catalog is **mid-migration**, so the committed snapshot's namespaces (currently `organization` and `playground`) will **grow as platform extensions migrate to `@lessly/tools`** — a namespace only appears once its tools carry a REST binding (tools without one are excluded until migrated). Regenerate the snapshot with `npx tsx scripts/generate.ts <catalog.json> src/gen && npm run sync-exports` against the live catalog (`https://api.lessly.dev/catalog/tools`).
+
 ## Usage
 
 Create a client with `createLesslyApp`, then call operations through the Proxy namespace tree:
@@ -17,10 +19,13 @@ const sdk = createLesslyApp({
   // getCsrfToken defaults to reading the `lessly_csrf` cookie; override for SSR/tests.
 });
 
-const { domains } = await sdk.tracking.domains.list({ page: 1 });
-await sdk.tracking.domains.create({ host: 'links.example.com' });
+const connectors = await sdk.organization.connectors.list({ productId: 'prod_123' });
+await sdk.organization.product.create({ name: 'Acme' });
 ```
 
+The available namespaces track the live catalog and grow as platform extensions migrate; check
+`package.json` `exports` (or `src/gen/manifest.gen.ts`) for what a given version exposes.
+
 Errors are surfaced as a typed `LesslyApiError` (`status`, `code`, `body`).
 
 ### TanStack Query
@@ -34,14 +39,14 @@ explicitly:
 // React example — works the same with any @tanstack/*-query adapter.
 import { useQuery, useMutation } from '@tanstack/react-query';
 import {
-  trackingDomainsListQueryOptions,
-  trackingDomainsCreateMutationOptions,
-} from '@lessly/sdk-app/tracking';
-
-function Domains() {
-  const { data } = useQuery(trackingDomainsListQueryOptions(sdk, { page: 1 }));
-  const create = useMutation(trackingDomainsCreateMutationOptions(sdk));
-  // create.mutate({ host: 'links.example.com' })
+  organizationConnectorsListQueryOptions,
+  organizationProductCreateMutationOptions,
+} from '@lessly/sdk-app/organization';
+
+function Connectors() {
+  const { data } = useQuery(organizationConnectorsListQueryOptions(sdk, { productId: 'prod_123' }));
+  const create = useMutation(organizationProductCreateMutationOptions(sdk));
+  // create.mutate({ name: 'Acme' })
 }
 ```
 
@@ -116,10 +121,15 @@ MUST publish with an explicit override:
 npm publish --registry https://registry.npmjs.org/
 ```
 
-Base-version resolution (the `npm view <pkg>@<channel> dist-tags` lookup inside the pipeline
-CLI) follows the same rule: it reads the registry from `package.json`'s `publishConfig.registry`
-first, falling back to the `.npmrc` `@lessly:registry` value if `publishConfig.registry` is
-absent. This requires no change to the CLI's `--channel`/`--catalog-url`/`--baseline` contract.
+Base-version resolution (the `npm view` lookups inside the pipeline CLI — both the per-channel
+version and the package-wide max-version probe) follows the same rule, and in **two** steps:
+it reads the registry from `package.json`'s `publishConfig.registry` first (falling back to the
+`.npmrc` `@lessly:registry` value if absent), **and** passes that registry as an explicit CLI
+scope override (`--@lessly:registry=<registry>`) on every `npm view`. The `--registry` flag alone
+is not enough: because the package is scoped `@lessly`, the `.npmrc` `@lessly:registry=<GAR>` entry
+would otherwise outrank it and silently resolve the lookup against GAR — which is exactly how an
+early run read GAR's `0.1.x` line instead of the empty npmjs registry and skipped the `0.2.0`
+floor. This requires no change to the CLI's `--channel`/`--catalog-url`/`--baseline` contract.
 
 ### Snapshot shape
 

package/docs/recipes/sdk-usage.md

@@ -18,10 +18,14 @@ const sdk = createLesslyApp({
   // getCsrfToken defaults to reading the `lessly_csrf` cookie; override for SSR/tests.
 });
 
-const { domains } = await sdk.tracking.domains.list({ page: 1 });
-await sdk.tracking.domains.create({ host: 'links.example.com' });
+const connectors = await sdk.organization.connectors.list({ productId: 'prod_123' });
+await sdk.organization.product.create({ name: 'Acme' });
 ```
 
+> The exact namespaces you see depend on the live catalog — see
+> [Namespaces and subpath imports](#namespaces-and-subpath-imports). The calls
+> above use `organization`; substitute the namespace/resource you need.
+
 `productId` is the active product — read it from your `./App` props or the
 `X-Product-Id` header (see APP-005), never decoded from a token.
 
@@ -35,7 +39,7 @@ distinguish platform-defined failure reasons:
 import { LesslyApiError } from '@lessly/sdk-app';
 
 try {
-  await sdk.tracking.domains.create({ host: 'links.example.com' });
+  await sdk.organization.product.create({ name: 'Acme' });
 } catch (err) {
   if (err instanceof LesslyApiError) {
     if (err.status === 409) {
@@ -57,14 +61,14 @@ instance explicitly:
 // React example — works the same with any @tanstack/*-query adapter.
 import { useQuery, useMutation } from '@tanstack/react-query';
 import {
-  trackingDomainsListQueryOptions,
-  trackingDomainsCreateMutationOptions,
-} from '@lessly/sdk-app/tracking';
-
-function Domains() {
-  const { data } = useQuery(trackingDomainsListQueryOptions(sdk, { page: 1 }));
-  const create = useMutation(trackingDomainsCreateMutationOptions(sdk));
-  // create.mutate({ host: 'links.example.com' })
+  organizationConnectorsListQueryOptions,
+  organizationProductCreateMutationOptions,
+} from '@lessly/sdk-app/organization';
+
+function Connectors() {
+  const { data } = useQuery(organizationConnectorsListQueryOptions(sdk, { productId: 'prod_123' }));
+  const create = useMutation(organizationProductCreateMutationOptions(sdk));
+  // create.mutate({ name: 'Acme' })
 }
 ```
 
@@ -73,7 +77,7 @@ so they also work directly with `queryClient.ensureQueryData(...)` and friends
 — useful for prefetching outside a component, e.g. in a route loader:
 
 ```ts
-await queryClient.ensureQueryData(trackingDomainsListQueryOptions(sdk, { page: 1 }));
+await queryClient.ensureQueryData(organizationConnectorsListQueryOptions(sdk, { productId: 'prod_123' }));
 ```
 
 Prefer these factories over hand-rolling calls against `sdk.<namespace>...`
@@ -83,12 +87,18 @@ it automatically when you run `npm i @lessly/sdk-app@latest`.
 
 ## Namespaces and subpath imports
 
-The SDK is organized by namespace (`tracking`, `mail`, `playground`, ...). Call
-operations off `sdk.<namespace>.<resource>.<action>(...)`, and import that
+The SDK is organized by namespace (currently `organization` and `playground`).
+Call operations off `sdk.<namespace>.<resource>.<action>(...)`, and import that
 namespace's option factories from the matching subpath,
 `@lessly/sdk-app/<namespace>` — not the package root. This keeps each App's
 bundle limited to the namespaces it actually uses.
 
+The available namespaces track the live catalog and **grow as platform
+extensions migrate to `@lessly/tools`** — a namespace appears here only once its
+tools carry a REST binding. Run `npm i @lessly/sdk-app@latest` to pick up newly
+migrated namespaces. To see exactly what a given version exposes, check its
+subpaths in `package.json` `exports`, or the `manifest.gen.ts` namespace list.
+
 ## What not to do
 
 - Don't `fetch` a platform host directly, and don't use any other HTTP client

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessly/sdk-app",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -49,5 +49,6 @@
       "import": "./dist/playground/index.js",
       "require": "./dist/playground/index.cjs"
     }
-  }
+  },
+  "sdkContentHash": "sha256:c6888491b9e25a037a38993fa524e1a5b646053465b66a88c5f7dfe3ba69ce70"
 }