@lessly/sdk-app 0.1.11

package/docs/recipes/sdk-usage.md

@@ -0,0 +1,99 @@
+# Recipe: calling the platform API
+
+How to reach Lessly platform data from an App. The normative rule is APP-001
+(all platform data access goes through `@lessly/sdk-app`) and APP-006 (prefer
+the generated option factories) — this page shows the *how*.
+
+## Create the client
+
+Create one client with `createLesslyApp` and 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' });
+```
+
+`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.
+
+## Handle errors with `LesslyApiError`
+
+Every failed call throws a typed `LesslyApiError` with `status`, `code`, and
+`body`. Branch on `code` (stable) rather than `status` alone when you need to
+distinguish platform-defined failure reasons:
+
+```ts
+import { LesslyApiError } from '@lessly/sdk-app';
+
+try {
+  await sdk.tracking.domains.create({ host: 'links.example.com' });
+} catch (err) {
+  if (err instanceof LesslyApiError) {
+    if (err.status === 409) {
+      // err.code / err.body carry the platform's structured reason
+    }
+  }
+  throw err;
+}
+```
+
+## Prefer the generated query/mutation option factories
+
+Each namespace subpath (`@lessly/sdk-app/<namespace>`) 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
+— useful for prefetching outside a component, e.g. in a route loader:
+
+```ts
+await queryClient.ensureQueryData(trackingDomainsListQueryOptions(sdk, { page: 1 }));
+```
+
+Prefer these factories over hand-rolling calls against `sdk.<namespace>...`
+directly (APP-006): they keep query keys, request shapes, and cache
+invalidation consistent with the published API surface, and stay in sync with
+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
+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.
+
+## What not to do
+
+- Don't `fetch` a platform host directly, and don't use any other HTTP client
+  for platform data (APP-001) — always go through `sdk` or the generated
+  factories.
+- Don't hand-roll request paths against the client when a
+  `*QueryOptions`/`*MutationOptions` factory already exists for that operation
+  (APP-006).

package/docs/rules.md

@@ -0,0 +1,89 @@
+# App Rules
+
+Normative rules for building a Lessly App on `@lessly/sdk-app`. Read this
+before writing code; see `README.md` for the map of the rest of the guide.
+
+Severity (RFC 2119): **MUST** blocks merge, **SHOULD** is a strong
+recommendation, **MAY** is an allowed option.
+
+Rule IDs (`APP-NNN`) are immutable once merged: a rule's ID and meaning never
+change, even if its wording is later clarified. Some of these rules cover
+ground shared with extensions and the platform's Module Federation host; where
+that's true, this file references the existing `FED-*` rule ID from the
+extensions-guide instead of restating it — go there for the full rule text,
+rationale, and examples.
+
+---
+
+### APP-001 (MUST) — All platform data access goes through `@lessly/sdk-app`
+
+Every read or write to a Lessly platform API MUST go through a
+`@lessly/sdk-app` client created with `createLesslyApp`, or through the
+generated `*QueryOptions`/`*MutationOptions` factories built on top of it. An
+App MUST NOT `fetch` a platform host directly, and MUST NOT use any other HTTP
+client to reach platform data.
+
+### APP-002 (MUST) — Frontend-only
+
+An App MUST NOT ship a backend service, a database, or an MCP endpoint. All
+of its logic runs in the browser, built on `@lessly/sdk-app` and the Module
+Federation contract below. If a feature needs server-side state or a
+service-to-service call, it belongs in an extension, not an App.
+
+### APP-003 (MUST) — Manifest is `lessly.app.yaml`, schema v1
+
+The manifest file is `lessly.app.yaml`, and its top-level surface is exactly:
+`app_schema_version: 1`, `id`, `title`, `version`, `nav` (with `nav.icon`). No
+other top-level field is valid — in particular, no extension/backend manifest
+field (`s2s`, `webhooks`, `billing`, `analytics`, `routing`, `public`, ...)
+belongs in an App manifest.
+
+### APP-004 (MUST) — Module Federation contract
+
+An App exposes `./App` as its Module Federation remote entry, implementing
+the shell's remote contract (FED-001). The Module Federation `name` MUST equal
+the manifest `id` (FED-004). React, React DOM, React Router, and `@lessly/ui`
+MUST be declared as shared singletons, never bundled (FED-005), using
+`@module-federation/vite` pinned at exactly `1.16.12` (FED-006). The asset
+base in federation mode is the absolute path `/~/<id>/`. The build MUST
+produce one merged dual-mode `dist/` covering both standalone and federation
+artifacts (FED-007). An App MAY additionally expose a data-only `./navigation`
+module (FED-011). This rule states the contract; it does not restate FED-001,
+FED-004, FED-005, FED-006, FED-007, or FED-011 — see those rules for exact
+wording, rationale, and examples.
+
+### APP-005 (MUST) — Auth is ambient; an App does not own it
+
+Authentication is ambient: the hosting shell owns cookies in production and a
+bearer proxy in local dev. An App MUST NOT implement login, token handling,
+refresh, or product switching — those belong to the shell. An App MUST read
+the active product from its props or the `X-Product-Id` header, never by
+decoding a token.
+
+An App MUST NOT rely on the `user` prop for anything beyond display. In
+dev-standalone mode, `user` is a stub (`{ id }` sourced from the local dev
+JWT, `displayName: 'Dev User'`) — it is not a real session. The real,
+shell-authenticated user only arrives once the app is composed via
+federation, through the `./App` props.
+
+### APP-006 (SHOULD) — Use the generated query/mutation option factories
+
+Prefer the generated `*QueryOptions`/`*MutationOptions` factories
+(`@lessly/sdk-app/<namespace>`) over hand-rolling request paths against the
+SDK client directly. They keep query keys, request shapes, and cache
+invalidation consistent with the published API surface, and stay in sync with
+it automatically on upgrade.
+
+### APP-007 (MUST) — Versioning hygiene
+
+Bump the manifest `version` on every release. Keep the SDK and this guide
+current with:
+
+```sh
+npm i @lessly/sdk-app@latest
+```
+
+Use this exact `@latest` form — not `npm update`. `@lessly/sdk-app` is
+pre-1.0 and pinned with a caret range, so `npm update` never crosses a minor
+version; since this SDK also bumps its minor version whenever the platform
+ships a new tool, `npm update` would never actually deliver those updates.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@lessly/sdk-app",
+  "version": "0.1.11",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "docs/*.md",
+    "docs/recipes",
+    "src/gen"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "generate": "tsx scripts/generate.ts fixtures/catalog.sample.json",
+    "ci": "tsx scripts/ci-run.ts",
+    "sync-exports": "tsx scripts/sync-exports.ts",
+    "build": "npm run sync-exports && tsup",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "json-schema-to-typescript": "^15.0.3",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./organization": {
+      "types": "./dist/organization/index.d.ts",
+      "import": "./dist/organization/index.js",
+      "require": "./dist/organization/index.cjs"
+    },
+    "./playground": {
+      "types": "./dist/playground/index.d.ts",
+      "import": "./dist/playground/index.js",
+      "require": "./dist/playground/index.cjs"
+    }
+  },
+  "sdkContentHash": "sha256:c6888491b9e25a037a38993fa524e1a5b646053465b66a88c5f7dfe3ba69ce70"
+}