@kromatv/sdk 0.1.40-canary.0

package/types/client/src/api/accounts/client.d.ts

@@ -0,0 +1,291 @@
+import { z } from 'zod';
+import type { RequestContext } from '../../core/client';
+import type { InviteToken, SessionId } from './ids';
+import { type AccountPatch, type Permission } from './schemas';
+/** Accounts, sessions, invitations and profile/PIN. */
+export default function accountsApi(ctx: RequestContext): {
+    passkeys: {
+        list: () => Promise<{
+            id: string & z.$brand<"PasskeyId">;
+            name: string;
+            createdAt: string;
+            lastUsed?: string | null | undefined;
+        }[]>;
+        delete: (id: import("./ids").PasskeyId) => Promise<void>;
+        registerStart: () => Promise<{
+            ceremonyId: string & z.$brand<"CeremonyId">;
+            options: {
+                publicKey: Record<string, unknown>;
+            };
+        }>;
+        registerFinish: (body: {
+            ceremonyId: import("./ids").CeremonyId;
+            name: string;
+            credential: import("./passkeys").WebAuthnCredential;
+        }) => Promise<{
+            id: string & z.$brand<"PasskeyId">;
+            name: string;
+            createdAt: string;
+            lastUsed?: string | null | undefined;
+        }>;
+        authStart: () => Promise<{
+            ceremonyId: string & z.$brand<"CeremonyId">;
+            options: {
+                publicKey: Record<string, unknown>;
+            };
+        }>;
+        authFinish: (body: {
+            ceremonyId: import("./ids").CeremonyId;
+            credential: import("./passkeys").WebAuthnCredential;
+        }) => Promise<{
+            token: string;
+            accessToken: string;
+            user: {
+                id: string & z.$brand<"UserId">;
+                email: string;
+                username: string;
+                avatarUrl?: string | null | undefined;
+                language?: string | null | undefined;
+                audioLanguage?: string | null | undefined;
+                subtitleLanguage?: string | null | undefined;
+                permissions: string[];
+                createdAt: string;
+                hasPin: boolean;
+            };
+        }>;
+    };
+    quickConnect: {
+        initiate: (prevSecret?: string) => Promise<{
+            code: string;
+            secret: string;
+            expiresInSec: number;
+            authorizeUrl: string | null;
+        }>;
+        poll: (secret: string) => Promise<import("./schemas").PairingStatus>;
+        authorize: (code: string) => Promise<void>;
+    };
+    /** Create an account and open a session. After the first (owner) account,
+     * `inviteToken` is required registration is invite-only. Does NOT set the
+     * token; the caller persists it, then calls `setAuthToken`. */
+    register: (email: string, username: string, password: string, inviteToken?: InviteToken) => Promise<{
+        token: string;
+        accessToken: string;
+        user: {
+            id: string & z.$brand<"UserId">;
+            email: string;
+            username: string;
+            avatarUrl?: string | null | undefined;
+            language?: string | null | undefined;
+            audioLanguage?: string | null | undefined;
+            subtitleLanguage?: string | null | undefined;
+            permissions: string[];
+            createdAt: string;
+            hasPin: boolean;
+        };
+    }>;
+    /** Log in with email-or-username + password. */
+    login: (identifier: string, password: string) => Promise<{
+        token: string;
+        accessToken: string;
+        user: {
+            id: string & z.$brand<"UserId">;
+            email: string;
+            username: string;
+            avatarUrl?: string | null | undefined;
+            language?: string | null | undefined;
+            audioLanguage?: string | null | undefined;
+            subtitleLanguage?: string | null | undefined;
+            permissions: string[];
+            createdAt: string;
+            hasPin: boolean;
+        };
+    }>;
+    /** Exchange the long-lived access token for a short-lived session token. Pass
+     * `pin` when switching into a PIN-locked profile (required on the first
+     * exchange; silent refreshes omit it). Throws `KromaApiError` 401 when the PIN
+     * is needed or the access token is invalid/expired. */
+    exchangeToken: (accessToken: string, pin?: string) => Promise<{
+        token: string;
+        user: {
+            id: string & z.$brand<"UserId">;
+            email: string;
+            username: string;
+            avatarUrl?: string | null | undefined;
+            language?: string | null | undefined;
+            audioLanguage?: string | null | undefined;
+            subtitleLanguage?: string | null | undefined;
+            permissions: string[];
+            createdAt: string;
+            hasPin: boolean;
+        };
+    }>;
+    /** Re-lock an access token (clear its PIN-verified flag) so the next exchange
+     * re-prompts for the PIN. Called when returning to the profile picker. */
+    relock: (accessToken: string) => Promise<void>;
+    /** Invalidate the current session server-side and revoke the device's access
+     * token, a full disconnect. */
+    logout: (accessToken?: string) => Promise<void>;
+    /** The currently-authenticated user (requires a token). */
+    me: () => Promise<{
+        user: {
+            id: string & z.$brand<"UserId">;
+            email: string;
+            username: string;
+            avatarUrl?: string | null | undefined;
+            language?: string | null | undefined;
+            audioLanguage?: string | null | undefined;
+            subtitleLanguage?: string | null | undefined;
+            permissions: string[];
+            createdAt: string;
+            hasPin: boolean;
+        };
+    }>;
+    /** Update the signed-in account's own profile. Sends only the keys present. */
+    update: (patch: AccountPatch) => Promise<{
+        user: {
+            id: string & z.$brand<"UserId">;
+            email: string;
+            username: string;
+            avatarUrl?: string | null | undefined;
+            language?: string | null | undefined;
+            audioLanguage?: string | null | undefined;
+            subtitleLanguage?: string | null | undefined;
+            permissions: string[];
+            createdAt: string;
+            hasPin: boolean;
+        };
+    }>;
+    /** Persist the preferred UI locale, synced across the account's devices.
+     * `null` clears it. */
+    updateLanguage: (language: string | null) => Promise<{
+        user: {
+            id: string & z.$brand<"UserId">;
+            email: string;
+            username: string;
+            avatarUrl?: string | null | undefined;
+            language?: string | null | undefined;
+            audioLanguage?: string | null | undefined;
+            subtitleLanguage?: string | null | undefined;
+            permissions: string[];
+            createdAt: string;
+            hasPin: boolean;
+        };
+    }>;
+    /** Change the password after verifying the current one. Throws
+     * `KromaApiError` on 401 (wrong current) / 400 (too short). A forgotten
+     * password goes through the owner-minted reset instead. */
+    changePassword: (current: string, next: string) => Promise<void>;
+    /** Public login-gate config read before any credential: whether the profile
+     * roster is public and whether any account exists yet. */
+    config: () => Promise<{
+        publicUserList: boolean;
+        hasAccounts: boolean;
+    }>;
+    /** Public profile list for the "Qui regarde ?" picker (no emails). Empty when
+     * the `publicUserList` setting is off. */
+    users: () => Promise<{
+        id: string & z.$brand<"UserId">;
+        username: string;
+        avatarUrl?: string | null | undefined;
+        hasPin: boolean;
+    }[]>;
+    /** Verify a profile-lock PIN with the remembered token (TV switch-in). Throws
+     * `KromaApiError` on 401 (wrong) / 429 (locked out; the error's `retryAfter`
+     * seconds are surfaced as a cooldown). */
+    verifyPin: (pin: string) => Promise<void>;
+    /** Set or rotate the PIN. `current` is required when one is already set. */
+    setPin: (pin: string, current?: string) => Promise<{
+        user: {
+            id: string & z.$brand<"UserId">;
+            email: string;
+            username: string;
+            avatarUrl?: string | null | undefined;
+            language?: string | null | undefined;
+            audioLanguage?: string | null | undefined;
+            subtitleLanguage?: string | null | undefined;
+            permissions: string[];
+            createdAt: string;
+            hasPin: boolean;
+        };
+    }>;
+    /** Clear the PIN, verifying `current`. */
+    clearPin: (current: string) => Promise<{
+        user: {
+            id: string & z.$brand<"UserId">;
+            email: string;
+            username: string;
+            avatarUrl?: string | null | undefined;
+            language?: string | null | undefined;
+            audioLanguage?: string | null | undefined;
+            subtitleLanguage?: string | null | undefined;
+            permissions: string[];
+            createdAt: string;
+            hasPin: boolean;
+        };
+    }>;
+    /** Upload the current user's avatar (raw image bytes). */
+    uploadAvatar: (file: Blob) => Promise<{
+        avatarUrl: string;
+    }>;
+    /** The account's active devices, newest first, the current one flagged. */
+    sessions: () => Promise<{
+        id: string & z.$brand<"SessionId">;
+        userAgent?: string | null | undefined;
+        createdAt: string;
+        lastSeen?: string | null | undefined;
+        current: boolean;
+    }[]>;
+    /** Revoke one of the account's own devices, signing it out. */
+    revokeSession: (id: SessionId) => Promise<void>;
+    /** Check a credential-reset token (public, used by the reset page). */
+    checkReset: (token: string) => Promise<{
+        valid: boolean;
+        username?: string | null | undefined;
+    }>;
+    /** Redeem a credential reset: the link token plus the code the owner read to
+     * the user. Throws `KromaApiError` 400 when invalid or locked. */
+    redeemReset: (token: string, code: string, password: string) => Promise<void>;
+    /** Ask the owner for a credential reset, from the sign-in screen. Always
+     * succeeds whether or not `identifier` names an account, so the screen never
+     * reveals who is registered; throttled per source IP. */
+    requestReset: (identifier: string) => Promise<void>;
+    /** Check an email-verification token (public, used by the verify page). */
+    checkEmailVerification: (token: string) => Promise<{
+        valid: boolean;
+        username?: string | null | undefined;
+    }>;
+    /** Confirm an email verification. Throws `KromaApiError` 400 when unknown,
+     * expired, used, or the address changed since minting. */
+    confirmEmailVerification: (token: string) => Promise<void>;
+    /** Pending invites (requires `users.manage`). */
+    invites: () => Promise<{
+        token: string & z.$brand<"InviteToken">;
+        permissions: ("library.manage" | "playback" | "reports.manage" | "requests.auto" | "requests.create" | "requests.manage" | "settings.manage" | "users.manage")[];
+        createdBy?: string | null | undefined;
+        createdAt: string;
+        expiresAt: number;
+        used: boolean;
+    }[]>;
+    /** Mint a registration invite (requires `users.manage`). */
+    createInvite: (opts?: {
+        permissions?: Permission[];
+        expiresInDays?: number;
+    }) => Promise<{
+        token: string & z.$brand<"InviteToken">;
+        permissions: ("library.manage" | "playback" | "reports.manage" | "requests.auto" | "requests.create" | "requests.manage" | "settings.manage" | "users.manage")[];
+        expiresAt: number;
+        url: string | null;
+    }>;
+    /** Check an invite token's validity (public, used by the join page). */
+    checkInvite: (token: InviteToken) => Promise<{
+        valid: boolean;
+        expiresAt?: number | undefined;
+    }>;
+    /** Revoke an invite (requires `users.manage`). */
+    revokeInvite: (token: InviteToken) => Promise<void>;
+};
+declare module '../../core/client' {
+    interface Domains {
+        accounts: ReturnType<typeof accountsApi>;
+    }
+}

package/types/client/src/api/accounts/ids.d.ts

@@ -0,0 +1,13 @@
+import type { z } from 'zod';
+export declare const UserId: z.core.$ZodBranded<z.ZodString, "UserId", "out">;
+export type UserId = z.infer<typeof UserId>;
+/** One signed-in device of an account, as `GET /auth/me/sessions` lists it.
+ * Not a `PlaybackSessionId`: this one revokes a login, that one stops a play. */
+export declare const SessionId: z.core.$ZodBranded<z.ZodString, "SessionId", "out">;
+export type SessionId = z.infer<typeof SessionId>;
+export declare const PasskeyId: z.core.$ZodBranded<z.ZodString, "PasskeyId", "out">;
+export type PasskeyId = z.infer<typeof PasskeyId>;
+export declare const CeremonyId: z.core.$ZodBranded<z.ZodString, "CeremonyId", "out">;
+export type CeremonyId = z.infer<typeof CeremonyId>;
+export declare const InviteToken: z.core.$ZodBranded<z.ZodString, "InviteToken", "out">;
+export type InviteToken = z.infer<typeof InviteToken>;

package/types/client/src/api/accounts/index.d.ts

@@ -0,0 +1,6 @@
+export * from './client';
+export * from './ids';
+export type { WebAuthnCeremony, WebAuthnCredential, WebAuthnOptions } from './passkeys';
+export * from './remembered';
+export * from './rules';
+export * from './schemas';

package/types/client/src/api/accounts/passkeys.d.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import type { RequestContext } from '../../core/http';
+import { CeremonyId, type PasskeyId } from './ids';
+/** Opaque WebAuthn ceremony payloads. Their shape is defined by the platform
+ * (`navigator.credentials`), not by us: the web layer converts the binary fields
+ * to and from `ArrayBuffer` around these. */
+export declare const WebAuthnOptions: z.ZodObject<{
+    publicKey: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type WebAuthnOptions = z.infer<typeof WebAuthnOptions>;
+export type WebAuthnCredential = Record<string, unknown>;
+/** What a ceremony start hands back: echo `ceremonyId` to the matching finish. */
+export declare const WebAuthnCeremony: z.ZodObject<{
+    ceremonyId: z.core.$ZodBranded<z.ZodString, "CeremonyId", "out">;
+    options: z.ZodObject<{
+        publicKey: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type WebAuthnCeremony = z.infer<typeof WebAuthnCeremony>;
+/** Passkeys: the WebAuthn registration and passwordless sign-in ceremonies. */
+export declare function passkeysApi(ctx: RequestContext): {
+    /** The account's registered passkeys, newest first. (Bearer.) */
+    list: () => Promise<{
+        id: string & z.$brand<"PasskeyId">;
+        name: string;
+        createdAt: string;
+        lastUsed?: string | null | undefined;
+    }[]>;
+    /** Remove one of the account's passkeys by id. (Bearer.) */
+    delete: (id: PasskeyId) => Promise<void>;
+    /** Begin registering a passkey. `options` feeds `navigator.credentials.create`. */
+    registerStart: () => Promise<{
+        ceremonyId: string & z.$brand<"CeremonyId">;
+        options: {
+            publicKey: Record<string, unknown>;
+        };
+    }>;
+    /** Finish registering a passkey with the browser's credential. */
+    registerFinish: (body: {
+        ceremonyId: CeremonyId;
+        name: string;
+        credential: WebAuthnCredential;
+    }) => Promise<{
+        id: string & z.$brand<"PasskeyId">;
+        name: string;
+        createdAt: string;
+        lastUsed?: string | null | undefined;
+    }>;
+    /** Begin usernameless (discoverable) passwordless sign-in. `options` feeds
+     * `navigator.credentials.get`; the browser lets the user pick which account.
+     * Public. */
+    authStart: () => Promise<{
+        ceremonyId: string & z.$brand<"CeremonyId">;
+        options: {
+            publicKey: Record<string, unknown>;
+        };
+    }>;
+    /** Finish passwordless sign-in with the browser's assertion, giving the same
+     * `{ token, accessToken, user }` as a password login. Public. */
+    authFinish: (body: {
+        ceremonyId: CeremonyId;
+        credential: WebAuthnCredential;
+    }) => Promise<{
+        token: string;
+        accessToken: string;
+        user: {
+            id: string & z.$brand<"UserId">;
+            email: string;
+            username: string;
+            avatarUrl?: string | null | undefined;
+            language?: string | null | undefined;
+            audioLanguage?: string | null | undefined;
+            subtitleLanguage?: string | null | undefined;
+            permissions: string[];
+            createdAt: string;
+            hasPin: boolean;
+        };
+    }>;
+};

package/types/client/src/api/accounts/quick-connect.d.ts

@@ -0,0 +1,23 @@
+import { type RequestContext } from '../../core/http';
+import { PairingStatus } from './schemas';
+/** Quick Connect: the code a device shows, and the poll that redeems it. */
+export declare function quickConnectApi(ctx: RequestContext): {
+    /** Start a request: a code to display plus a secret to poll with. Pass
+     * `prevSecret` when rotating an expiring code so the server revokes the old
+     * one up front instead of leaving it to lapse on TTL. */
+    initiate: (prevSecret?: string) => Promise<{
+        code: string;
+        secret: string;
+        expiresInSec: number;
+        authorizeUrl: string | null;
+    }>;
+    /** Poll a request by its secret.
+     *
+     * The secret rides in a header rather than the query: a URL is written into
+     * every access log the request passes through, and this one redeems a 90-day
+     * credential. A server old enough to demand `?secret=` refuses that request,
+     * and only such a server is re-polled the legacy way, once and then for good. */
+    poll: (secret: string) => Promise<PairingStatus>;
+    /** Approve a device's code (requires the approver's token). */
+    authorize: (code: string) => Promise<void>;
+};

package/types/client/src/api/accounts/remembered.d.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import type { UserId } from './ids';
+declare const StoredSession: z.ZodObject<{
+    accessToken: z.ZodString;
+    user: z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodString, "UserId", "out">;
+        avatarUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        audioLanguage: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        subtitleLanguage: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        email: z.ZodCatch<z.ZodString>;
+        username: z.ZodCatch<z.ZodString>;
+        createdAt: z.ZodCatch<z.ZodString>;
+        hasPin: z.ZodCatch<z.ZodBoolean>;
+        permissions: z.ZodCatch<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    serverUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StoredSession = z.infer<typeof StoredSession>;
+/** A KROMA server the TV remembers, so it can hold profiles from several at once
+ * and order the picker by most-recently-used. The stored row's gaps are filled
+ * in on the way out, so a reader never has to. */
+export declare const SavedServer: z.ZodObject<{
+    url: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+    lastUsedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type SavedServer = z.infer<typeof SavedServer>;
+/** Normalize a server origin for comparison (drop trailing slashes). Tolerates
+ * null/undefined (TV call sites may pass an unset serverUrl). */
+export declare function normalizeServerUrl(u?: string | null): string;
+/** The active session, or null when signed out. */
+export declare function loadSession(): StoredSession | null;
+/** Set the active session AND remember the account on this device. De-dupes by
+ * the (serverUrl, user.id) pair so the same user id on two servers is two
+ * distinct profiles; with no serverUrl this is the by-user-id de-dupe web uses. */
+export declare function saveSession(session: StoredSession): void;
+/** Clear only the ACTIVE session (e.g. "switch profile"). Remembered accounts
+ * stay, so switching back to one is still password-free. */
+export declare function clearSession(): void;
+/** Accounts that have signed in on this device (most-recent first). Pass a
+ * `serverUrl` to get only that server's remembered profiles. */
+export declare function loadAccounts(serverUrl?: string): StoredSession[];
+/** Forget one remembered account (full sign-out for it). With a `serverUrl` only
+ * the (serverUrl, user.id) pair is dropped; without one, every account with that
+ * user id is dropped (web's single-server behaviour). Also clears the active
+ * session when it was the one being forgotten. */
+export declare function forgetAccount(userId: UserId, serverUrl?: string): void;
+/** Saved KROMA servers, most-recently-used first. */
+export declare function loadServers(): SavedServer[];
+/** Add or update a saved server (idempotent on normalized URL). */
+export declare function saveServer(server: {
+    url: string;
+    name?: string | null;
+    lastUsedAt?: number;
+}): SavedServer[];
+/** Bump a server's `lastUsedAt` (and add it if unknown), for picker ordering. */
+export declare function touchServer(url: string): void;
+/** Drop a saved server and every remembered account on it; clears the active
+ * session if it belonged to that server. */
+export declare function forgetServer(url: string): void;
+/** One-time upgrade from the pre-multi-server storage: seed `kroma.servers` from
+ * the old single `kroma.serverUrl`, stamp legacy accounts/session with it, then
+ * drop the legacy key. A no-op once migrated or on a fresh (web) install. */
+export declare function migrateStorage(): void;
+export {};

package/types/client/src/api/accounts/rules.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export declare const emailRule: z.ZodPipe<z.ZodString, z.ZodEmail>;
+export declare const passwordRule: z.ZodString;
+export declare const usernameRule: z.ZodString;
+export declare const pinRule: z.ZodString;
+export declare const isEmail: (s: string) => boolean;
+export declare const isPassword: (s: string) => boolean;
+export declare const isUsername: (s: string) => boolean;
+export declare const isPin: (s: string) => boolean;