@lessly/sdk-app 0.1.11

package/README.md

@@ -0,0 +1,134 @@
+# @lessly/sdk-app
+
+The Lessly SDK for App is a TypeScript SDK that provides runtime bindings and type-safe generated code for interacting with Lessly Platform APIs and services. This package generates type definitions and client bindings from API catalogs, enabling developers to build applications that consume Lessly platform services with full type safety and autocompletion.
+
+**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.
+
+## Usage
+
+Create a client with `createLesslyApp`, then call operations through the Proxy namespace tree:
+
+```ts
+import { createLesslyApp } from '@lessly/sdk-app';
+
+const sdk = createLesslyApp({
+  baseUrl: 'https://api.lessly.dev',
+  productId: 'prod_123',
+  // 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' });
+```
+
+Errors are surfaced as a typed `LesslyApiError` (`status`, `code`, `body`).
+
+### TanStack Query
+
+Each namespace subpath (`@lessly/sdk-app/<namespace>`) also ships framework-agnostic
+query/mutation **option factories** — plain objects, not hooks — usable with any
+TanStack Query adapter (React, Solid, Vue, Svelte). You pass the `sdk` instance
+explicitly:
+
+```ts
+// 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' })
+}
+```
+
+The factories return `{ queryKey, queryFn }` (and `{ mutationKey, mutationFn }`),
+so they also work directly with `queryClient.ensureQueryData(...)` and friends.
+This package has **no runtime dependencies** — bring your own TanStack Query adapter.
+
+## Publishing
+
+This repo holds source only — **humans push code to GitHub, builds run in dev-console
+via Cloud Build, and the published package lives on npmjs.** Nothing commits or pushes back to
+this repo automatically; the catalog snapshot and changelog are stored in GCS, not in git.
+
+Cloud Build clones the repo read-only and drives the runner-agnostic pipeline CLI:
+
+```sh
+npm run ci -- --channel <next|latest> --catalog-url <URL> [--baseline <path>]
+```
+
+- `--channel` — the npm dist-tag to publish under (`next` for staging, `latest` for production).
+- `--catalog-url` — the public catalog endpoint, fetched with an anonymous GET
+  (staging `https://api.lessly.dev/catalog/tools`, production `https://api.lessly.com/catalog/tools`).
+- `--baseline` — path to the previous catalog snapshot (downloaded from GCS) used for the
+  content-hash gate and the semver diff-classifier. **Omit it for the first publish.**
+
+The very first publish on the (empty) npmjs registry is floored at **`0.2.0`**, not `0.1.0`,
+so it lands strictly above the legacy GAR `0.1.x` line that existing consumers pinned (e.g.
+`^0.1.1`). This mirrors the `@lessly/ui` migration (GAR `0.1.0` → npmjs `0.2.0`). Once a version
+exists on a channel's dist-tag, normal semver bumping (and the recovery patch-bump) takes over.
+The floor is keyed off the **registry**, not the flag: if the channel's dist-tag resolves to
+nothing (empty npmjs), the run takes the first-publish path even when Cloud Build passes a stored
+(GAR-era) baseline — the baseline is ignored and the freshly-fetched catalog ships as the `0.2.0`
+initial release. So Cloud Build may keep passing the stored baseline through the migration without
+erroring.
+
+Because npm versions are immutable **package-wide** (not per-dist-tag), a missing channel tag does
+not by itself mean an empty registry. The pipeline therefore also checks the package-wide max
+version: if a tag is absent but the package already carries versions under another tag (e.g. `next`
+published `0.2.0` and a first production run finds `latest` absent), it force-publishes a **fresh
+patch bumped past that max** so `npm publish --tag <channel>` seeds the tag without a 409 on the
+already-published version. The genuine `0.2.0` first-publish floor applies only when the package
+has **no versions anywhere**.
+
+The CLI fetches the catalog, regenerates `src/gen`, and compares against the baseline. When
+the generated output changed it bumps the version in `package.json` (base version resolved
+from `npm view @lessly/sdk-app dist-tags` against the configured registry, per channel —
+see "Registry: public npmjs" below), appends `CHANGELOG.md`, and writes:
+
+- `out/result.json` — `{ publish_needed, level, version }` (always written).
+- `out/new-snapshot.json` — the new snapshot (written only when a publish is needed; see
+  "Snapshot shape" below).
+
+The CLI performs **no git, gcloud, or npm-publish operations** — it is pure Node. Cloud Build
+reads `out/result.json`, then runs `npm publish` and uploads the new snapshot + changelog to
+GCS itself.
+
+### Registry: public npmjs
+
+The package now publishes to **public npmjs**, not GAR: `package.json` sets
+`publishConfig.registry = https://registry.npmjs.org/` and `publishConfig.access = public`.
+Cloud Build publishes each channel under its own dist-tag — `next` for staging, `latest` for
+production.
+
+**Scope-override gotcha:** this repo's `.npmrc` still carries `@lessly:registry=<GAR URL>` for
+dependency-resolution stability (nothing in this package's runtime deps is scoped
+`@lessly`, so that entry is safe to keep). A scoped `.npmrc` registry entry **outranks**
+`publishConfig.registry` for npm's own resolution, so if the `rebuild_sdk` Cloud Build step
+were to run a bare `npm publish`, it would silently target GAR instead of npmjs. The step
+MUST publish with an explicit override:
+
+```sh
+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.
+
+### Snapshot shape
+
+`out/new-snapshot.json` is now a wrapper, `{ catalog, docsHash }`, rather than a bare catalog —
+`docsHash` is the content hash of the **shipped** guide (the `docs/*.md` + `docs/recipes` files,
+matching the `files` globs; internal `docs/superpowers/` is excluded), added so a docs-only change
+(no catalog diff) still triggers a PATCH publish. The file remains an **opaque blob** to Cloud
+Build: store it in GCS exactly as written and pass it back verbatim as `--baseline` on the next
+run. Older, bare-catalog baselines from before this change are still accepted: because such a
+baseline predates in-package docs, the first run against it publishes a **one-time migration
+PATCH** (when shipped docs are present) that ships the guide and seeds the wrapper snapshot —
+after which docs-change detection is fully hash-based.