@omen.dog/sdk 1.0.0 → 1.1.0

package/README.md

@@ -110,6 +110,78 @@ console.log(webhook.secret); // save this!
 const valid = await omen.webhooks.verify(rawBody, signature, secret);
 ```
 
+### Sparks (partner awards)
+
+Award money-backed Sparks and catalog items to your users from a prepaid pool
+(buy/manage it in the Developer Portal → Sparks Pool).
+
+> **Approved Partner Apps only.** Awarding mints real Sparks, so `award`,
+> `awardBatch`, and `items.awardCatalog` require the app to be an approved
+> Partner App (Developer Portal → Partner Program). Unapproved apps get
+> `403 partner_required`. Funding a pool does not require approval.
+
+```ts
+// Award Sparks (pass idempotencyKey to make retries safe)
+await omen.sparks.award({
+  userId, amount: 250, reason: 'Beat level 10',
+  idempotencyKey: `level10:${userId}`,
+});
+
+// Batch (≤100, best-effort per item)
+await omen.sparks.awardBatch([
+  { userId: 'u1', amount: 100 },
+  { userId: 'u2', amount: 100 },
+]);
+
+// Award an open-shop item or avatar trait — paid from your pool at list price
+await omen.items.awardCatalog({ userId, catalogType: 'store', catalogItemId: 'theme_lava' });
+
+// Pool status
+const pool = await omen.sparks.pool();
+
+// Mint a short-lived display token for the UI kit (backend only — needs your
+// app's OAuth client secret). Pass it to <omen-sparks-balance>/<omen-inventory>.
+const token = omen.sparks.displayToken({ userId, secret: process.env.OMEN_CLIENT_SECRET! });
+```
+
+#### UI kit (embeddable widgets)
+
+```html
+<script src="https://sdk.omen.dog/v1/ui-kit.js"></script>
+<omen-sparks-balance token="DISPLAY_TOKEN"></omen-sparks-balance>
+<omen-inventory token="DISPLAY_TOKEN" limit="24"></omen-inventory>
+<script>OmenUI.toast({ amount: 250, message: 'Level cleared!' })</script>
+```
+
+Restyle via CSS variables (`--omen-bg`, `--omen-accent`, `--omen-spark`, …),
+`::part()` selectors, or `theme="bare"` to ship your own CSS entirely.
+
+### Shared avatar (Embedded Avatar Kit)
+
+Put the shared Omen avatar inside your app — display it, let users edit it
+in-place, browse the trait catalog, and gift traits from your Sparks pool.
+
+```ts
+// Public render URL (pass version from avatar:saved / user.avatar_updated to bust caches)
+const url = omen.avatar.renderUrl(userId, { version });
+
+// Mint a short-lived editor token for <omen-avatar-editor> (backend only)
+const token = omen.avatar.editorToken({ userId, secret: process.env.OMEN_CLIENT_SECRET! });
+
+// Enumerate the shared catalog — trait ids, names, rarities, ✦ prices (public, no auth).
+// Pass { editorToken } and each trait's `locked` reflects that user's ownership.
+const { catalog, rarityPricing } = await omen.avatar.catalog();
+
+// Gift a trait app-funded — your pool pays list price, the user pays nothing
+await omen.items.awardCatalog({
+  userId, catalogType: 'avatar_trait', catalogItemId: 'hair/export-01.svg',
+});
+```
+
+Trait ids are `category/file.svg` paths and double as public preview SVGs at
+`https://omen.dog/avatar/{traitId}`. Common traits are free for everyone and
+can't be awarded.
+
 ## Creation Runtime Types
 
 For creation developers — get autocomplete for the `omen.*` global:
@@ -121,6 +193,42 @@ const save = await omen.load();
 omen.score(100);
 ```
 
+## Child Re-Login (`ChildLogin`)
+
+A safe, thin wrapper over the child device-grant flow for Tier-3 apps that sign
+in Omen child accounts (F263). It's a separate export — it uses your OAuth
+`clientId`/`clientSecret`, not a `dev_` token — and is also available from the
+server-only subpath `@omen.dog/sdk/child-login`. `scope:'child'` is always sent,
+RFC 8628 errors map to a calm status union instead of throwing, and scope is
+preserved across refresh rotation. Tokens never leave your server.
+
+```ts
+import { ChildLogin } from '@omen.dog/sdk/child-login';
+
+const child = new ChildLogin({
+  clientId: process.env.OMEN_CLIENT_ID!,
+  clientSecret: process.env.OMEN_CLIENT_SECRET!,   // omit for public/PKCE clients
+  webhookSecret: process.env.OMEN_WEBHOOK_SECRET!,
+});
+
+const grant = await child.deviceStart({ deviceName: "Astrid's iPad" });
+await child.notify({ device_code: grant.device_code, username: 'astrid' }); // cold start
+const res = await child.pollUntil(grant.device_code);  // honors interval + slow_down
+if (res.status === 'approved') {
+  const session = child.seal(res.tokens!); // store in your httpOnly session; res.rebind = card data
+}
+
+// flip the child's screen the instant a parent approves:
+if (child.verifyWebhook(rawBody, req.headers['x-omen-signature'])) { /* notify the device */ }
+```
+
+Pair it with the in-context `<omen-child-login>` web component (zero-dep, themeable,
+talks only to your own routes). See [omen.dog/docs#child-relogin-kit](https://omen.dog/docs).
+
+The canonical child-side state machine is exported too (`deriveInitialState`,
+`reduce`, `displayGroup`, `CHILD_LOGIN_STATES`) for apps building custom UI on the
+same kindness.
+
 ## Error Handling
 
 ```ts

package/dist/child-login.d.mts

@@ -0,0 +1,230 @@
+type ChildPollStatus =
+  | 'approved'
+  | 'pending'
+  | 'slow_down'
+  | 'denied'
+  | 'expired'
+  | 'error';
+
+interface ChildTokens {
+  access_token: string;
+  refresh_token?: string;
+  token_type: string;
+  expires_in?: number;
+  scope?: string;
+}
+
+interface ChildRebind {
+  child_id: string;
+  display_name: string;
+  avatar_url: string | null;
+  suggested_device_name: string;
+}
+
+interface PollResult {
+  status: ChildPollStatus;
+  tokens?: ChildTokens;
+  rebind?: ChildRebind | null;
+  deviceToken?: string | null;
+  error?: string;
+}
+
+interface SealedSession {
+  accessToken: string;
+  refreshToken: string | null;
+  scope: string;
+  accessExpiresAt: number;
+  deviceToken?: string;
+}
+
+interface ChildLoginApprovedPayload {
+  child_id: string;
+  device_id: string | null;
+  device_name: string | null;
+  approved_at: string;
+}
+
+type ChildLoginState =
+  | 'trusted'
+  | 'known'
+  | 'cold'
+  | 'pending'
+  | 'approved'
+  | 'denied'
+  | 'blocked'
+  | 'paused'
+  | 'expired'
+  | 'offline';
+
+type ChildLoginSignal =
+  | 'ask'
+  | 'pending'
+  | 'slow_down'
+  | 'approved'
+  | 'denied'
+  | 'blocked'
+  | 'paused'
+  | 'expired'
+  | 'offline'
+  | 'online'
+  | 'reset';
+
+type ChildLoginDisplayGroup =
+  | 'ready'
+  | 'waiting'
+  | 'approved'
+  | 'ask-grown-up'
+  | 'expired'
+  | 'offline';
+
+interface ChildLoginContext {
+  online?: boolean;
+  trustedDevice?: boolean;
+  identity?: unknown | null;
+}
+
+declare const CHILD_LOGIN_STATES: ChildLoginState[];
+declare const ASK_GROWN_UP_STATES: ChildLoginState[];
+declare const ENTRY_STATES: ChildLoginState[];
+
+declare function deriveInitialState(ctx?: ChildLoginContext): ChildLoginState;
+declare function reduce(state: ChildLoginState, signal: ChildLoginSignal, ctx?: ChildLoginContext): ChildLoginState;
+declare function displayGroup(state: ChildLoginState): ChildLoginDisplayGroup;
+
+interface ChildLoginOptions {
+    /** Your OAuth client_id (from the Developer Portal). Required. */
+    clientId: string;
+    /** Your client_secret. Omit for public (PKCE) clients. */
+    clientSecret?: string;
+    /** Base URL for the Omen API. Defaults to `https://omen.dog`. */
+    baseUrl?: string;
+    /** The endpoint secret for your `child.login.approved` webhook (enables `verifyWebhook`). */
+    webhookSecret?: string;
+}
+interface DeviceStartOptions {
+    /** The child's Omen userId from a previous session. Omit for a cold start (parent picks). */
+    loginHint?: string;
+    /** Stable per-device id you generate and persist (enables trusted-device auto-approval). */
+    deviceId?: string;
+    /** Human-readable device name shown to the parent ("Astrid's iPad"). */
+    deviceName?: string;
+    /** A trusted-device token from a prior approval — auto-approves on first poll. */
+    deviceToken?: string;
+}
+interface DeviceStartResult {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+interface ChildIdentity {
+    child: {
+        display_name: string;
+        avatar_url: string | null;
+    };
+    guardians: Array<{
+        display_name: string;
+        avatar_url: string | null;
+    }>;
+}
+interface PollUntilOptions {
+    /** Abort the wait (e.g. the child navigated away, or your webhook already flipped the screen). */
+    signal?: AbortSignal;
+    /** Called after every non-terminal poll with the current status — useful for logging. */
+    onStatus?: (status: PollResult['status']) => void;
+    /** Override the starting interval (seconds). Defaults to the grant's `interval`, or 5. */
+    intervalSeconds?: number;
+}
+
+/**
+ * F263 Child Re-Login — the official server-side primitive for third-party apps
+ * that sign in child accounts.
+ *
+ * It is a thin, safe wrapper over the Phase-1 device-grant API with the right
+ * defaults made non-optional: `scope:'child'` is always sent, RFC 8628 errors
+ * are mapped to a calm status union instead of thrown, and `scope` is preserved
+ * across refresh. Token custody stays on YOUR server — nothing here ever returns
+ * a token to the browser.
+ *
+ * @example
+ * ```ts
+ * import { ChildLogin } from '@omen.dog/sdk';
+ *
+ * const child = new ChildLogin({
+ *   clientId: process.env.OMEN_CLIENT_ID!,
+ *   clientSecret: process.env.OMEN_CLIENT_SECRET!,
+ *   webhookSecret: process.env.OMEN_WEBHOOK_SECRET!,
+ * });
+ *
+ * // 1. start a grant on a fresh device
+ * const grant = await child.deviceStart({ deviceName: "Astrid's iPad" });
+ * // 2. she types her username → ask the family
+ * await child.notify({ device_code: grant.device_code, username: 'astrid' });
+ * // 3. poll until a grown-up approves (calm status union, never throws on pending)
+ * const result = await child.pollUntil(grant.device_code);
+ * if (result.status === 'approved') {
+ *   const session = child.seal(result.tokens!);   // store in your httpOnly session
+ * }
+ * ```
+ */
+declare class ChildLogin {
+    private readonly clientId;
+    private readonly clientSecret?;
+    private readonly webhookSecret?;
+    readonly baseUrl: string;
+    constructor(options: ChildLoginOptions);
+    /** Start a child device-authorization grant. `scope:'child'` is always sent. */
+    deviceStart(options?: DeviceStartOptions): Promise<DeviceStartResult>;
+    /**
+     * Tell Omen which child is logging in. With `username` this is the cold-start
+     * path (no prior `login_hint`); without it, it re-pings the family for a known
+     * child. Always resolves `{ ok: true }` (enumeration-safe) on the cold path.
+     */
+    notify(args: {
+        device_code: string;
+        username?: string;
+    }): Promise<{
+        ok: boolean;
+    }>;
+    /**
+     * Poll the token endpoint once. Returns a calm status union — `pending`,
+     * `slow_down`, `denied`, `expired`, `error`, or `approved` (with tokens,
+     * rebind blob and one-time device_token). Never throws on a normal RFC 8628
+     * polling response; only network failures reject.
+     */
+    poll(deviceCode: string): Promise<PollResult>;
+    /**
+     * Poll until the grant reaches a terminal state, honouring `interval` and
+     * widening it by 5s on every `slow_down` (RFC 8628 §3.5). Prefer driving the
+     * flip from the `child.login.approved` webhook; use this as the fallback.
+     */
+    pollUntil(deviceCode: string, options?: PollUntilOptions): Promise<PollResult>;
+    /**
+     * Refresh a child access token. `scope:'child'` is preserved across rotation,
+     * and the old refresh token is single-use (Omen rotates it).
+     */
+    refresh(refreshToken: string): Promise<ChildTokens>;
+    /** Fetch the consent-gated identity bundle with the child's access token. */
+    childIdentity(accessToken: string): Promise<ChildIdentity>;
+    /** Normalise a token grant into a record for your httpOnly session store. */
+    seal(tokens: ChildTokens & {
+        device_token?: string;
+    }, opts?: {
+        now?: number;
+        deviceToken?: string | null;
+    }): SealedSession;
+    /** Whether a sealed session's access token needs a refresh before use. */
+    accessExpired(record: SealedSession, opts?: {
+        now?: number;
+        skewMs?: number;
+    }): boolean;
+    /** Verify a `child.login.approved` webhook signature (uses your `webhookSecret`). */
+    verifyWebhook(payload: string, signature: string, secret?: string | undefined): boolean;
+    /** Verify + parse a `child.login.approved` webhook. Returns null if the signature is invalid. */
+    parseApproval(payload: string, signature: string, secret?: string | undefined): ChildLoginApprovedPayload | null;
+    private post;
+}
+
+export { ASK_GROWN_UP_STATES, CHILD_LOGIN_STATES, type ChildIdentity, ChildLogin, type ChildLoginApprovedPayload, type ChildLoginContext, type ChildLoginDisplayGroup, type ChildLoginOptions, type ChildLoginSignal, type ChildLoginState, type ChildRebind, type ChildTokens, type DeviceStartOptions, type DeviceStartResult, ENTRY_STATES, type PollResult, type PollUntilOptions, type SealedSession, deriveInitialState, displayGroup, reduce };

package/dist/child-login.d.ts

@@ -0,0 +1,230 @@
+type ChildPollStatus =
+  | 'approved'
+  | 'pending'
+  | 'slow_down'
+  | 'denied'
+  | 'expired'
+  | 'error';
+
+interface ChildTokens {
+  access_token: string;
+  refresh_token?: string;
+  token_type: string;
+  expires_in?: number;
+  scope?: string;
+}
+
+interface ChildRebind {
+  child_id: string;
+  display_name: string;
+  avatar_url: string | null;
+  suggested_device_name: string;
+}
+
+interface PollResult {
+  status: ChildPollStatus;
+  tokens?: ChildTokens;
+  rebind?: ChildRebind | null;
+  deviceToken?: string | null;
+  error?: string;
+}
+
+interface SealedSession {
+  accessToken: string;
+  refreshToken: string | null;
+  scope: string;
+  accessExpiresAt: number;
+  deviceToken?: string;
+}
+
+interface ChildLoginApprovedPayload {
+  child_id: string;
+  device_id: string | null;
+  device_name: string | null;
+  approved_at: string;
+}
+
+type ChildLoginState =
+  | 'trusted'
+  | 'known'
+  | 'cold'
+  | 'pending'
+  | 'approved'
+  | 'denied'
+  | 'blocked'
+  | 'paused'
+  | 'expired'
+  | 'offline';
+
+type ChildLoginSignal =
+  | 'ask'
+  | 'pending'
+  | 'slow_down'
+  | 'approved'
+  | 'denied'
+  | 'blocked'
+  | 'paused'
+  | 'expired'
+  | 'offline'
+  | 'online'
+  | 'reset';
+
+type ChildLoginDisplayGroup =
+  | 'ready'
+  | 'waiting'
+  | 'approved'
+  | 'ask-grown-up'
+  | 'expired'
+  | 'offline';
+
+interface ChildLoginContext {
+  online?: boolean;
+  trustedDevice?: boolean;
+  identity?: unknown | null;
+}
+
+declare const CHILD_LOGIN_STATES: ChildLoginState[];
+declare const ASK_GROWN_UP_STATES: ChildLoginState[];
+declare const ENTRY_STATES: ChildLoginState[];
+
+declare function deriveInitialState(ctx?: ChildLoginContext): ChildLoginState;
+declare function reduce(state: ChildLoginState, signal: ChildLoginSignal, ctx?: ChildLoginContext): ChildLoginState;
+declare function displayGroup(state: ChildLoginState): ChildLoginDisplayGroup;
+
+interface ChildLoginOptions {
+    /** Your OAuth client_id (from the Developer Portal). Required. */
+    clientId: string;
+    /** Your client_secret. Omit for public (PKCE) clients. */
+    clientSecret?: string;
+    /** Base URL for the Omen API. Defaults to `https://omen.dog`. */
+    baseUrl?: string;
+    /** The endpoint secret for your `child.login.approved` webhook (enables `verifyWebhook`). */
+    webhookSecret?: string;
+}
+interface DeviceStartOptions {
+    /** The child's Omen userId from a previous session. Omit for a cold start (parent picks). */
+    loginHint?: string;
+    /** Stable per-device id you generate and persist (enables trusted-device auto-approval). */
+    deviceId?: string;
+    /** Human-readable device name shown to the parent ("Astrid's iPad"). */
+    deviceName?: string;
+    /** A trusted-device token from a prior approval — auto-approves on first poll. */
+    deviceToken?: string;
+}
+interface DeviceStartResult {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+interface ChildIdentity {
+    child: {
+        display_name: string;
+        avatar_url: string | null;
+    };
+    guardians: Array<{
+        display_name: string;
+        avatar_url: string | null;
+    }>;
+}
+interface PollUntilOptions {
+    /** Abort the wait (e.g. the child navigated away, or your webhook already flipped the screen). */
+    signal?: AbortSignal;
+    /** Called after every non-terminal poll with the current status — useful for logging. */
+    onStatus?: (status: PollResult['status']) => void;
+    /** Override the starting interval (seconds). Defaults to the grant's `interval`, or 5. */
+    intervalSeconds?: number;
+}
+
+/**
+ * F263 Child Re-Login — the official server-side primitive for third-party apps
+ * that sign in child accounts.
+ *
+ * It is a thin, safe wrapper over the Phase-1 device-grant API with the right
+ * defaults made non-optional: `scope:'child'` is always sent, RFC 8628 errors
+ * are mapped to a calm status union instead of thrown, and `scope` is preserved
+ * across refresh. Token custody stays on YOUR server — nothing here ever returns
+ * a token to the browser.
+ *
+ * @example
+ * ```ts
+ * import { ChildLogin } from '@omen.dog/sdk';
+ *
+ * const child = new ChildLogin({
+ *   clientId: process.env.OMEN_CLIENT_ID!,
+ *   clientSecret: process.env.OMEN_CLIENT_SECRET!,
+ *   webhookSecret: process.env.OMEN_WEBHOOK_SECRET!,
+ * });
+ *
+ * // 1. start a grant on a fresh device
+ * const grant = await child.deviceStart({ deviceName: "Astrid's iPad" });
+ * // 2. she types her username → ask the family
+ * await child.notify({ device_code: grant.device_code, username: 'astrid' });
+ * // 3. poll until a grown-up approves (calm status union, never throws on pending)
+ * const result = await child.pollUntil(grant.device_code);
+ * if (result.status === 'approved') {
+ *   const session = child.seal(result.tokens!);   // store in your httpOnly session
+ * }
+ * ```
+ */
+declare class ChildLogin {
+    private readonly clientId;
+    private readonly clientSecret?;
+    private readonly webhookSecret?;
+    readonly baseUrl: string;
+    constructor(options: ChildLoginOptions);
+    /** Start a child device-authorization grant. `scope:'child'` is always sent. */
+    deviceStart(options?: DeviceStartOptions): Promise<DeviceStartResult>;
+    /**
+     * Tell Omen which child is logging in. With `username` this is the cold-start
+     * path (no prior `login_hint`); without it, it re-pings the family for a known
+     * child. Always resolves `{ ok: true }` (enumeration-safe) on the cold path.
+     */
+    notify(args: {
+        device_code: string;
+        username?: string;
+    }): Promise<{
+        ok: boolean;
+    }>;
+    /**
+     * Poll the token endpoint once. Returns a calm status union — `pending`,
+     * `slow_down`, `denied`, `expired`, `error`, or `approved` (with tokens,
+     * rebind blob and one-time device_token). Never throws on a normal RFC 8628
+     * polling response; only network failures reject.
+     */
+    poll(deviceCode: string): Promise<PollResult>;
+    /**
+     * Poll until the grant reaches a terminal state, honouring `interval` and
+     * widening it by 5s on every `slow_down` (RFC 8628 §3.5). Prefer driving the
+     * flip from the `child.login.approved` webhook; use this as the fallback.
+     */
+    pollUntil(deviceCode: string, options?: PollUntilOptions): Promise<PollResult>;
+    /**
+     * Refresh a child access token. `scope:'child'` is preserved across rotation,
+     * and the old refresh token is single-use (Omen rotates it).
+     */
+    refresh(refreshToken: string): Promise<ChildTokens>;
+    /** Fetch the consent-gated identity bundle with the child's access token. */
+    childIdentity(accessToken: string): Promise<ChildIdentity>;
+    /** Normalise a token grant into a record for your httpOnly session store. */
+    seal(tokens: ChildTokens & {
+        device_token?: string;
+    }, opts?: {
+        now?: number;
+        deviceToken?: string | null;
+    }): SealedSession;
+    /** Whether a sealed session's access token needs a refresh before use. */
+    accessExpired(record: SealedSession, opts?: {
+        now?: number;
+        skewMs?: number;
+    }): boolean;
+    /** Verify a `child.login.approved` webhook signature (uses your `webhookSecret`). */
+    verifyWebhook(payload: string, signature: string, secret?: string | undefined): boolean;
+    /** Verify + parse a `child.login.approved` webhook. Returns null if the signature is invalid. */
+    parseApproval(payload: string, signature: string, secret?: string | undefined): ChildLoginApprovedPayload | null;
+    private post;
+}
+
+export { ASK_GROWN_UP_STATES, CHILD_LOGIN_STATES, type ChildIdentity, ChildLogin, type ChildLoginApprovedPayload, type ChildLoginContext, type ChildLoginDisplayGroup, type ChildLoginOptions, type ChildLoginSignal, type ChildLoginState, type ChildRebind, type ChildTokens, type DeviceStartOptions, type DeviceStartResult, ENTRY_STATES, type PollResult, type PollUntilOptions, type SealedSession, deriveInitialState, displayGroup, reduce };