@skystate/core

Framework-agnostic SkyState client for public state, auth token storage, and per-user state.

Install

Public npm installation is pending. The intended package name is @skystate/core.

In this repository:

npm install
npm run build
npm run typecheck
npm test

Basic Usage

import { createSkyStateClient } from '@skystate/core';

const client = createSkyStateClient({
  account: 'acc_example',
  project: 'my-app',
  environment: 'production',
});

await client.init();

const banner = client.publicState.get('banner', { enabled: false });

client.setAuthTokens({ idToken, refreshToken });

const theme = client.userState.get('theme', 'dark');
client.userState.set('theme', 'light');

account, project, and environment are required. apiUrl defaults to https://api.skystate.io.

Public API

| API | Signature | Description | |---|---|---| | createSkyStateClient | (options: SkyStateClientOptions) => SkyStateClient | Creates a framework-agnostic client. | | client.init | () => Promise<void> | Initializes public state and auth state. | | client.dispose | () => void | Releases client resources. | | client.publicState.get | (key: string, fallback?: unknown) => unknown | Reads a public-state key. | | client.setAuthTokens | ({ idToken, refreshToken }) => void | Attaches hosted-auth tokens. | | client.clearAuthTokens | (error?: AuthError) => void | Clears local auth state. | | client.logout | () => Promise<void> | Signs out through SkyState. | | client.userState.get | (key: string, fallback?: unknown) => unknown | Reads a user-state key. | | client.userState.set | (key: string, value: unknown) => void | Writes a user-state key. | | client.userState.subscribe | (key: string, listener: () => void) => () => void | Subscribes to a user-state key. | | client.userState.draft | <T>(key: string, fallback?: T) => UserStateDraftHandle<T> | Creates a local draft handle for edit-then-save UI. |

User State

User state requires end-user SkyState auth tokens. After tokens are set, the client can read, write, and draft keyed values for the signed-in user.

client.setAuthTokens({ idToken, refreshToken });

const theme = client.userState.get('theme', 'dark');
client.userState.set('theme', 'light');

const draft = client.userState.draft('profile', { displayName: '' });
draft.set((current) => ({ ...current, displayName: 'Ada' }));
draft.push();

Writes update local subscribers immediately and are persisted by the SDK. Temporary network, sign-in renewal, concurrent update, validation, and permission issues are surfaced through snapshots and provider error callbacks in wrapper SDKs.

Draft handles expose get, committed, hasDraft, getDraft, set, push, discard, subscribe, and dispose.

Value-Only SDK Contract

The v1 SDK surface is intentionally value-only. Public snapshots expose status, data, and errors; keyed SDK accessors return values. Use the console, CLI, or REST API when you need inspection, audit, or history metadata.

Exports

| Export | Description | |---|---| | createSkyStateClient() | Creates a SkyStateClient. | | SkyStateError, SkyStateErrorCode | Typed SDK errors and error-code union. | | SkyStateClient, SkyStateClientOptions, ClientSnapshot, ClientLifecycle | Client and lifecycle types. | | PublicStateSnapshot, AuthSnapshot, UserStateSnapshot, AuthError | Snapshot and auth error types. | | PublicStateAccessor, UserStateAccessor, UserStateDraftHandle | Public accessor and draft types. | | decodeJwtPayload() | Decode a JWT payload for inspection. | | buildStorageKey(), createLocalStorage(), createMemoryStorage(), AuthTokenStorage | Auth token storage helpers and type. | | toJsonPointer(), resolvePointer() | Lower-level JSON Pointer helpers. State accessors take top-level keys. | | INITIAL_SNAPSHOT | Initial client snapshot constant. | | assertNever() | Exhaustiveness helper for discriminated unions. | | RefreshOutcome | Token-refresh outcome type for advanced integrations. |

Docs

See the public docs at /docs/sdk/core/.