@lessly/sdk-app 0.3.0 → 0.4.0

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