@frontfriend/sdk 1.2.3 → 1.2.5

package/README.md

@@ -326,6 +326,10 @@ npx frontfriend init --tag <tag-name-or-id>
 
 `--version` takes a Release ID, not an SDK version. A Studio refusal, such as a missing login or no access to the Design System, stops initialization.
 
+After the tokens, an online `init` signed in as a person registers the App named in `frontfriend.config.js` on its tag (`--tag`, then `tag`) with its `framework` and `primitive`, so `update` and the design reads find it. When Studio refuses the registration, `init` stops with the reason; the installed tokens stay. With a machine credential, or with `--no-register`, `init` installs the selected tokens and never registers the App or changes its Release tag (see [Builds and CI](#builds-and-ci)). During an outage it keeps the tokens and asks you to run `init` again. When the App adopts contracts and `frontfriend.lock.json` pins a design snapshot, `init` also writes that snapshot's contracts to `.frontfriend/design/` and, when they are missing or belong to another snapshot, its rules to `.frontfriend/rules/`: the same files `update` writes.
+
+`frontfriend.lock.json` lists its contract pins by slug, then kind, and its `adoptionDigest` does not depend on the order of the pins. A lock written by an earlier SDK in another order is still valid; `update` keeps its bytes until the adoption itself changes.
+
 Every online `init` keeps a verified copy of the selected tokens in `.frontfriend/artifacts`. When Studio is unreachable (network failure, timeout or server error), a signed-in `init` restores that copy. A first install during an outage has no copy to restore.
 
 ### Offline tokens
@@ -340,11 +344,21 @@ npx frontfriend init --offline
 
 The default API uses the production token CDN automatically. For a custom API, set `token-cdn-url`, `FF_TOKEN_CDN_URL`, or `--token-cdn-url`. Set `token-cdn-url: false` to disable CDN delivery.
 
-Downloads validate artifact identity and integrity. Access refusals and invalid data stop initialization. Token delivery does not update component files, register the application, or publish changes. Run `connect` or `design sync` online for those operations. External fonts and images have their own availability.
+Downloads validate artifact identity and integrity. Access refusals and invalid data stop initialization. Token delivery does not update component files or publish changes; `init --offline` also does not register the application or write contracts. Run `init`, `connect` or `design sync` online for those operations. External fonts and images have their own availability.
+
+## Builds and CI
+
+Builds authenticate with a machine credential: create one with the `components:read` permission on the **API keys** page of the Workspace in Studio, and set it as `FF_AUTH_TOKEN` through your CI secret store. Do not commit it to project configuration or print it in build logs. Online token delivery, private components and design rules require it; `init --offline` does not.
+
+In CI or a Docker build, select the tag the build ships:
+
+```sh
+FF_AUTH_TOKEN=<machine credential> npx frontfriend init --tag <tag-name>
+```
 
-## CI authentication
+A machine credential is read-only for the App. `init` installs the tokens of the requested tag and prints `Build mode: App registration skipped (machine credential).`; it never registers the App or moves its Release tag in Studio, so a preview build on `next` does not move a production App off `base`. Pass `--no-register` to get the same behavior with any credential. Studio never changes an App for a machine credential either: it answers the registration of an earlier SDK with the App unchanged, so those builds also install the requested tag and leave the App on its own tag. If Studio refuses a registration with `MACHINE_CREDENTIAL_READ_ONLY`, `init` reports the registration as skipped and succeeds.
 
-Set `FF_AUTH_TOKEN` through your CI secret store for commands that need access to your workspace. Do not commit it to project configuration or print it in build logs. Online token delivery, private components and design rules require it; `init --offline` does not.
+`update`, `adopt`, `download` and `add` with a machine credential use the App's current Release tag. They stop with a message when the selection would bind the App or move it to another tag. `connect` stops at its login step: it registers the App, which needs a person's login (`frontfriend login`, with `FF_AUTH_TOKEN` unset). Change an App's tag in Studio or with a person's login.
 
 ## Existing Tailwind clients
 

package/dist/application-adoption-lock.d.ts

@@ -3,6 +3,7 @@ import type {
   AdoptionComponent,
   AdoptionDigestLock,
   ApplicationLock,
+  DesignAdoption,
 } from "./application-adoption";
 
 export type {
@@ -26,6 +27,18 @@ export type ParsedApplicationLock =
 
 export function sortedObject<T>(value: Record<string, T>): Record<string, T>;
 export function adoptionDigest(lock: AdoptionDigestLock): string;
+export function hasValidAdoptionDigest(lock: AdoptionDigestLock): boolean;
+export function sameAdoption(
+  left: AdoptionDigestLock,
+  right: AdoptionDigestLock,
+): boolean;
+export function sortContractPins<T extends { slug: string; kind: string }>(
+  pins: T[],
+): T[];
+export function canonicalDesignAdoption<T extends DesignAdoption>(design: T): T;
+export function canonicalApplicationLock<T extends AdoptionDigestLock>(
+  lock: T,
+): T;
 export function normalizeLock(value: unknown): ParsedApplicationLock;
 export function parseApplicationLock(content: unknown): ParsedApplicationLock;
 export function serializeApplicationLock(lock: unknown): string;