@hanzo/base 0.2.0 → 0.2.1

package/dist/client-Ckpi5rr9.d.ts

@@ -0,0 +1,368 @@
+/**
+ * State version tracking (Convex-inspired).
+ *
+ * Each query result is tagged with a StateVersion so the client can
+ * detect ordering, replay transitions, and drive optimistic rollbacks.
+ */
+interface StateVersion {
+    /** Monotonically increasing counter bumped on every query-set change. */
+    querySet: number;
+    /** Server timestamp (microseconds since epoch) of the latest known event. */
+    ts: bigint;
+    /** Identity hash -- changes when the authenticated user changes. */
+    identity: number;
+}
+type Modification = {
+    type: 'QueryUpdated';
+    collection: string;
+    record: BaseRecord;
+} | {
+    type: 'QueryRemoved';
+    collection: string;
+    id: string;
+} | {
+    type: 'QueryFailed';
+    collection: string;
+    error: string;
+};
+interface Transition {
+    startVersion: StateVersion;
+    endVersion: StateVersion;
+    modifications: Modification[];
+}
+/** Minimal record shape that every Base record satisfies. */
+interface BaseRecord {
+    id: string;
+    collectionId?: string;
+    collectionName?: string;
+    created?: string;
+    updated?: string;
+    [key: string]: unknown;
+}
+declare class VersionTracker {
+    private _version;
+    private _history;
+    private readonly _maxHistory;
+    constructor(maxHistory?: number);
+    get current(): Readonly<StateVersion>;
+    get history(): readonly Transition[];
+    /**
+     * Advance the version and record a transition.
+     * Returns the new version.
+     */
+    advance(modifications: Modification[], serverTs?: bigint): StateVersion;
+    /** Update identity hash (e.g. on auth change). */
+    setIdentity(identity: number): void;
+    /** Update the high-water timestamp without bumping querySet. */
+    updateTimestamp(ts: bigint): void;
+    /** Simple FNV-1a-like hash for identity derivation. */
+    static hashIdentity(token: string): number;
+}
+
+interface QueryKey {
+    collection: string;
+    filter: string;
+}
+type StoreCallback = (records: BaseRecord[]) => void;
+declare class QueryStore {
+    private readonly _slots;
+    private readonly _optimistic;
+    private readonly _version;
+    get version(): Readonly<StateVersion>;
+    /** Return cached effective (server+optimistic) result or undefined. */
+    getQuery(collection: string, filter?: string): BaseRecord[] | undefined;
+    /** Overwrite the server-truth cache for a query and notify. */
+    setQuery(collection: string, filter: string, data: BaseRecord[]): void;
+    /** Apply an optimistic create/update. Returns a mutationId for rollback. */
+    optimisticSet(collection: string, record: BaseRecord): string;
+    /** Apply an optimistic delete. */
+    optimisticDelete(collection: string, id: string): string;
+    /** Remove a single optimistic mutation and re-derive. */
+    rollbackOptimistic(mutationId: string): void;
+    /** Drop all optimistic entries for a collection. */
+    clearOptimistic(collection: string): void;
+    /**
+     * Apply a realtime SSE event from the server.
+     * `action` is one of "create", "update", "delete".
+     */
+    applyServerUpdate(collection: string, action: 'create' | 'update' | 'delete', record: BaseRecord): void;
+    /** Subscribe to effective-state changes for a query. Returns unsubscribe. */
+    subscribe(collection: string, filter: string, callback: StoreCallback): () => void;
+    private _notify;
+    private _notifyCollection;
+}
+
+/**
+ * RealtimeService -- SSE-based subscription manager.
+ *
+ * Features:
+ * - Query deduplication via hash(collection+topic) with reference counting
+ * - Auto-reconnect with exponential backoff
+ * - Max observed timestamp tracking
+ * - Connection state notifications
+ */
+
+type ConnectionState = 'disconnected' | 'connecting' | 'connected';
+interface RealtimeEvent {
+    action: 'create' | 'update' | 'delete';
+    record: BaseRecord;
+}
+type RealtimeCallback = (event: RealtimeEvent) => void;
+type ConnectionCallback = (state: ConnectionState) => void;
+declare class RealtimeService {
+    private readonly _baseUrl;
+    private readonly _getToken;
+    private _eventSource;
+    private _state;
+    private _connectionListeners;
+    /** Dedup map: hash -> Subscription. */
+    private _subscriptions;
+    /** SSE client id assigned by the server on connect. */
+    private _clientId;
+    /** Reconnect state. */
+    private _reconnectAttempts;
+    private _reconnectTimer;
+    private _maxReconnectDelay;
+    private _baseReconnectDelay;
+    /** High-water mark of observed server timestamps. */
+    private _maxTimestamp;
+    /** Set to true when disconnect() is called explicitly. */
+    private _intentionalDisconnect;
+    constructor(baseUrl: string, getToken: () => string);
+    get state(): ConnectionState;
+    get maxTimestamp(): bigint;
+    /**
+     * Subscribe to realtime events for a collection topic.
+     *
+     * Topic is usually "*" (all changes) or a record id.
+     * Returns an unsubscribe function.
+     */
+    subscribe(collection: string, topic: string, callback: RealtimeCallback): () => void;
+    /** Remove all subscribers for a topic, or all topics if none specified. */
+    unsubscribe(topic?: string): void;
+    /** Register a connection-state listener. Returns unsubscribe. */
+    onConnectionChange(callback: ConnectionCallback): () => void;
+    /** Explicitly disconnect. */
+    disconnect(): void;
+    private _connect;
+    private _handleMessage;
+    /** Submit current subscription set to the server via POST. */
+    private _submitSubscriptions;
+    private _scheduleReconnect;
+    private _clearReconnect;
+    private _setState;
+    private _hash;
+}
+
+/**
+ * CollectionService -- typed CRUD + auth + realtime for a single collection.
+ *
+ * API-compatible with the upstream RecordService interface, extended with
+ * reactive features (subscribe/unsubscribe, optimistic writes).
+ */
+
+interface ListResult$1<T = BaseRecord> {
+    page: number;
+    perPage: number;
+    totalItems: number;
+    totalPages: number;
+    items: T[];
+}
+interface RecordQueryOptions {
+    filter?: string;
+    sort?: string;
+    expand?: string;
+    fields?: string;
+    headers?: Record<string, string>;
+    /** Extra query params merged into the URL. */
+    query?: Record<string, string>;
+    /** Request-scoped AbortSignal. */
+    signal?: AbortSignal;
+}
+interface RecordFullListOptions extends RecordQueryOptions {
+    /** Batch size for pagination (default 200). */
+    batch?: number;
+}
+interface FileOptions {
+    thumb?: string;
+    token?: string;
+}
+interface AuthResponse<T = BaseRecord> {
+    token: string;
+    record: T;
+}
+interface OAuth2Options {
+    provider: string;
+    code: string;
+    codeVerifier: string;
+    redirectUrl: string;
+    createData?: Record<string, unknown>;
+}
+declare class CollectionService {
+    readonly collectionIdOrName: string;
+    private readonly _baseUrl;
+    private readonly _getToken;
+    private readonly _setAuth;
+    private readonly _store;
+    private readonly _realtime;
+    constructor(collectionIdOrName: string, baseUrl: string, getToken: () => string, setAuth: (token: string, record: BaseRecord) => void, store: QueryStore, realtime: RealtimeService);
+    getList<T extends BaseRecord = BaseRecord>(page?: number, perPage?: number, options?: RecordQueryOptions): Promise<ListResult$1<T>>;
+    getFullList<T extends BaseRecord = BaseRecord>(options?: RecordFullListOptions): Promise<T[]>;
+    getOne<T extends BaseRecord = BaseRecord>(id: string, options?: RecordQueryOptions): Promise<T>;
+    getFirstListItem<T extends BaseRecord = BaseRecord>(filter: string, options?: RecordQueryOptions): Promise<T>;
+    create<T extends BaseRecord = BaseRecord>(data: Record<string, unknown> | FormData, options?: RecordQueryOptions): Promise<T>;
+    update<T extends BaseRecord = BaseRecord>(id: string, data: Record<string, unknown> | FormData, options?: RecordQueryOptions): Promise<T>;
+    delete(id: string, options?: RecordQueryOptions): Promise<boolean>;
+    /**
+     * Subscribe to realtime events for this collection.
+     * `topic` is "*" for all changes or a specific record id.
+     */
+    subscribe(topic: string, callback: RealtimeCallback): () => void;
+    /** Unsubscribe from a specific topic or all topics for this collection. */
+    unsubscribe(topic?: string): void;
+    authWithPassword<T extends BaseRecord = BaseRecord>(identity: string, password: string, options?: RecordQueryOptions): Promise<AuthResponse<T>>;
+    authWithOAuth2<T extends BaseRecord = BaseRecord>(oauthOptions: OAuth2Options, options?: RecordQueryOptions): Promise<AuthResponse<T>>;
+    requestVerification(email: string, options?: RecordQueryOptions): Promise<boolean>;
+    confirmVerification(token: string, options?: RecordQueryOptions): Promise<boolean>;
+    requestPasswordReset(email: string, options?: RecordQueryOptions): Promise<boolean>;
+    confirmPasswordReset(token: string, password: string, passwordConfirm: string, options?: RecordQueryOptions): Promise<boolean>;
+    private _collectionPath;
+    private _applyOptions;
+    private _request;
+}
+interface ClientResponseErrorData {
+    url: string;
+    status: number;
+    data: Record<string, unknown>;
+}
+declare class ClientResponseError extends Error {
+    url: string;
+    status: number;
+    data: Record<string, unknown>;
+    isAbort: boolean;
+    constructor(errorData: ClientResponseErrorData);
+    toJSON(): ClientResponseErrorData;
+}
+
+interface AuthStore {
+    token: string;
+    record: BaseRecord | null;
+    onChange(callback: (token: string, record: BaseRecord | null) => void): () => void;
+    save(token: string, record: BaseRecord | null): void;
+    clear(): void;
+    readonly isValid: boolean;
+}
+type AuthChangeCallback = (token: string, record: BaseRecord | null) => void;
+/**
+ * Default in-memory auth store.
+ * Validates JWT exp claim without external dependencies.
+ */
+declare class MemoryAuthStore implements AuthStore {
+    private _token;
+    private _record;
+    private _listeners;
+    get token(): string;
+    get record(): BaseRecord | null;
+    get isValid(): boolean;
+    save(token: string, record: BaseRecord | null): void;
+    clear(): void;
+    onChange(callback: AuthChangeCallback): () => void;
+    private _notify;
+}
+declare class FileService {
+    private readonly _baseUrl;
+    constructor(baseUrl: string);
+    /**
+     * Build a full URL to a record file.
+     * Compatible with Base's files.getURL().
+     */
+    getURL(record: BaseRecord, filename: string, options?: FileOptions): string;
+}
+interface ClientConfig {
+    /** Base URL of the Hanzo Base instance (e.g. "https://myapp.hanzo.ai"). */
+    url: string;
+    /** Optional external auth store. Defaults to in-memory store. */
+    authStore?: AuthStore;
+}
+interface ListOptions {
+    filter?: string;
+    sort?: string;
+    expand?: string;
+    fields?: string;
+    page?: number;
+    perPage?: number;
+}
+interface ListResult<T = BaseRecord> {
+    page: number;
+    perPage: number;
+    totalItems: number;
+    totalPages: number;
+    items: T[];
+}
+declare class BaseClient {
+    readonly url: string;
+    readonly authStore: AuthStore;
+    readonly store: QueryStore;
+    readonly realtime: RealtimeService;
+    readonly files: FileService;
+    private readonly _versionTracker;
+    private readonly _collections;
+    /**
+     * Create a BaseClient.
+     *
+     * Accepts either a config object or a plain URL string for convenience:
+     *   new BaseClient('https://myapp.hanzo.ai')
+     *   new BaseClient({ url: 'https://myapp.hanzo.ai' })
+     */
+    constructor(configOrUrl: ClientConfig | string);
+    /** Get or create a CollectionService for the given name/id. */
+    collection(nameOrId: string): CollectionService;
+    /** Current state version from the QueryStore's internal tracker. */
+    get version(): Readonly<StateVersion>;
+    private _headers;
+    private _request;
+    list(collection: string, options?: ListOptions): Promise<ListResult>;
+    getOne(collection: string, id: string, options?: Pick<ListOptions, 'expand' | 'fields'>): Promise<BaseRecord>;
+    create(collection: string, data: Record<string, unknown>): Promise<BaseRecord>;
+    update(collection: string, id: string, data: Record<string, unknown>): Promise<BaseRecord>;
+    delete(collection: string, id: string): Promise<void>;
+    signInWithPassword(collection: string, identity: string, password: string): Promise<{
+        token: string;
+        record: BaseRecord;
+    }>;
+    signUp(collection: string, data: Record<string, unknown>): Promise<BaseRecord>;
+    refreshAuth(collection: string): Promise<{
+        token: string;
+        record: BaseRecord;
+    }>;
+    signOut(): void;
+    /**
+     * Send a raw request to the Base API.
+     * Convenience for endpoints not covered by CollectionService.
+     */
+    send<T = unknown>(path: string, options?: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: string | FormData;
+        query?: Record<string, string>;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    health(): Promise<{
+        code: number;
+        message: string;
+    }>;
+    /**
+     * Subscribe to realtime events for a collection topic.
+     * Also wires events into the QueryStore automatically.
+     */
+    subscribeAndSync(collection: string, topic?: string, callback?: (e: RealtimeEvent) => void): () => void;
+    /** Disconnect realtime and clear caches. */
+    disconnect(): void;
+}
+declare class BaseClientError extends Error {
+    readonly status: number;
+    readonly detail: unknown;
+    constructor(status: number, detail: unknown);
+}
+
+export { type AuthChangeCallback as A, BaseClient as B, type ClientConfig as C, type FileOptions as F, type ListOptions as L, MemoryAuthStore as M, type OAuth2Options as O, type QueryKey as Q, type RealtimeCallback as R, type StateVersion as S, type Transition as T, VersionTracker as V, type AuthResponse as a, type AuthStore as b, BaseClientError as c, type BaseRecord as d, ClientResponseError as e, type ClientResponseErrorData as f, CollectionService as g, type ConnectionCallback as h, type ConnectionState as i, FileService as j, type ListResult as k, type Modification as l, QueryStore as m, type RealtimeEvent as n, RealtimeService as o, type RecordFullListOptions as p, type RecordQueryOptions as q, type StoreCallback as r };

package/dist/compat/index.d.ts

@@ -1 +1,203 @@
-export { AsyncAuthStore, default as Base, BaseAuthStore, ClientResponseError, LocalAuthStore, default as PocketBase, cookieParse, cookieSerialize, default, getTokenPayload, isTokenExpired, normalizeUnknownQueryParams } from 'pocketbase';
+import { d as BaseRecord, b as AuthStore, A as AuthChangeCallback } from '../client-Ckpi5rr9.js';
+export { a as AuthResponse, B as Base, B as BaseClient, C as ClientConfig, e as ClientResponseError, f as ClientResponseErrorData, F as FileOptions, L as ListOptions, k as ListResult, M as MemoryAuthStore, O as OAuth2Options, p as RecordFullListOptions, q as RecordQueryOptions, B as default } from '../client-Ckpi5rr9.js';
+
+/**
+ * Schema types — collection + field model shapes the admin UI needs.
+ *
+ * Defined natively in @hanzo/base so the SDK has no upstream
+ * dependency. Admin pages import `CollectionModel` / `CollectionField`
+ * directly from `@hanzo/base`.
+ */
+
+/**
+ * A single field in a collection schema.
+ *
+ * Field types and their option shapes mirror the Base admin API
+ * (`/v1/collections/{id}` → `fields[]`), so existing admin UIs read
+ * the structure unchanged.
+ */
+interface CollectionField {
+    id: string;
+    name: string;
+    type: 'text' | 'number' | 'bool' | 'email' | 'url' | 'editor' | 'date' | 'autodate' | 'select' | 'json' | 'file' | 'relation' | 'password';
+    system?: boolean;
+    required?: boolean;
+    presentable?: boolean;
+    hidden?: boolean;
+    unique?: boolean;
+    min?: number | string | null;
+    max?: number | string | null;
+    pattern?: string;
+    maxSelect?: number;
+    values?: string[];
+    collectionId?: string;
+    cascadeDelete?: boolean;
+    minSelect?: number;
+    options?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * A collection definition. Mirrors the Base admin API
+ * `/v1/collections/{id}` payload.
+ *
+ * `type` selects the back-end behaviour: `base` is a regular collection,
+ * `auth` is an auth collection (users), `view` is a virtual read-only
+ * SQL-defined view.
+ */
+interface CollectionModel {
+    id: string;
+    name: string;
+    type: 'base' | 'auth' | 'view';
+    system?: boolean;
+    fields: CollectionField[];
+    indexes?: string[];
+    listRule?: string | null;
+    viewRule?: string | null;
+    createRule?: string | null;
+    updateRule?: string | null;
+    deleteRule?: string | null;
+    authRule?: string | null;
+    manageRule?: string | null;
+    authAlert?: {
+        enabled?: boolean;
+        emailTemplate?: Record<string, unknown>;
+    };
+    oauth2?: Record<string, unknown>;
+    passwordAuth?: {
+        enabled?: boolean;
+        identityFields?: string[];
+    };
+    otp?: Record<string, unknown>;
+    mfa?: Record<string, unknown>;
+    fileToken?: Record<string, unknown>;
+    authToken?: Record<string, unknown>;
+    passwordResetToken?: Record<string, unknown>;
+    emailChangeToken?: Record<string, unknown>;
+    verificationToken?: Record<string, unknown>;
+    viewQuery?: string;
+    [key: string]: unknown;
+}
+/**
+ * Alias for `BaseRecord` so consumers migrating from the upstream
+ * client can keep using `RecordModel`. New code should prefer
+ * `BaseRecord` from `./state.js`.
+ */
+type RecordModel = BaseRecord;
+
+/**
+ * Auth-store implementations beyond the in-memory default.
+ *
+ * Native `LocalAuthStore` / `AsyncAuthStore` implementations so the
+ * SDK has zero upstream client dependency. The shape matches the
+ * legacy client's auth stores so existing apps migrating to
+ * `@hanzo/base` keep working.
+ */
+
+/**
+ * Type alias matching the upstream interface name. New code should use
+ * `AuthStore`.
+ */
+type BaseAuthStore = AuthStore;
+/**
+ * Synchronous localStorage-backed auth store. Suitable for browser SPAs.
+ * Falls back to in-memory storage when `window.localStorage` is absent
+ * (SSR, sandboxed iframes, etc.).
+ */
+declare class LocalAuthStore implements AuthStore {
+    private _storageKey;
+    private _listeners;
+    private _memToken;
+    private _memRecord;
+    constructor(storageKey?: string);
+    private get _storage();
+    private _read;
+    private _write;
+    get token(): string;
+    get record(): BaseRecord | null;
+    get isValid(): boolean;
+    save(token: string, record: BaseRecord | null): void;
+    clear(): void;
+    onChange(callback: AuthChangeCallback): () => void;
+    private _notify;
+}
+/**
+ * Async auth store — wraps any async storage backend (cookies via
+ * fetch, encrypted SecureStore on mobile, KV namespace on the edge,
+ * etc.). Reads and writes are buffered through an in-memory cache so
+ * the `token`/`record` accessors stay synchronous (matching upstream).
+ *
+ * Pass a `save` function that persists the serialized payload to your
+ * backend, and an `initial` value loaded synchronously at app boot.
+ */
+declare class AsyncAuthStore implements AuthStore {
+    private _token;
+    private _record;
+    private _listeners;
+    private readonly _save;
+    private readonly _clear?;
+    constructor(config: {
+        save: (serialized: string) => Promise<void> | void;
+        initial?: string | null;
+        clear?: () => Promise<void> | void;
+    });
+    get token(): string;
+    get record(): BaseRecord | null;
+    get isValid(): boolean;
+    save(token: string, record: BaseRecord | null): void;
+    clear(): void;
+    onChange(callback: AuthChangeCallback): () => void;
+    private _notify;
+}
+
+/**
+ * JWT + cookie helpers — small utilities the compat layer used to
+ * re-export from the upstream client. Implemented natively so the SDK
+ * has zero upstream dependency.
+ */
+/**
+ * Decode the payload of a JWT without verifying its signature.
+ * Returns `null` for malformed tokens. Safe for browser + Node use
+ * (relies only on global `atob`).
+ */
+declare function getTokenPayload<T = Record<string, unknown>>(token: string): T | null;
+/**
+ * Check whether a JWT's `exp` claim has passed.
+ * `expirationThreshold` (seconds) is subtracted from `exp` to expire
+ * tokens early — set this when you want to refresh before the actual
+ * expiration. Tokens without an `exp` claim are treated as
+ * non-expiring.
+ */
+declare function isTokenExpired(token: string, expirationThreshold?: number): boolean;
+/**
+ * Cookie parsing — extracts a name→value map from a Set-Cookie or
+ * Cookie header value. Decodes URI-encoded values. Mirrors the
+ * `cookie` npm package's signature so it's drop-in for the upstream
+ * client's `cookieParse`.
+ */
+declare function cookieParse(input: string): Record<string, string>;
+interface CookieSerializeOptions {
+    encode?: (value: string) => string;
+    maxAge?: number;
+    domain?: string;
+    path?: string;
+    expires?: Date;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none' | boolean;
+    priority?: 'low' | 'medium' | 'high';
+}
+/**
+ * Cookie serialization — builds a `Set-Cookie` header value.
+ * `encode` defaults to `encodeURIComponent`. Throws if the name or
+ * encoded value contain invalid characters.
+ */
+declare function cookieSerialize(name: string, value: string, options?: CookieSerializeOptions): string;
+/**
+ * Normalize a query-param record so values are always strings (or
+ * arrays of strings). Mirrors the upstream `normalizeUnknownQueryParams`
+ * helper used by the auto-encoding URL builder. Nullish entries are
+ * dropped; non-primitive entries are JSON-stringified.
+ */
+declare function normalizeUnknownQueryParams(params: Record<string, unknown> | null | undefined): Record<string, string | string[]>;
+
+export { AsyncAuthStore, AuthChangeCallback, AuthStore, type BaseAuthStore, BaseRecord, type CollectionField, type CollectionModel, type CookieSerializeOptions, LocalAuthStore, type RecordModel, cookieParse, cookieSerialize, getTokenPayload, isTokenExpired, normalizeUnknownQueryParams };

package/dist/compat/index.js

@@ -1,3 +1,4 @@
-export { AsyncAuthStore, default as Base, BaseAuthStore, ClientResponseError, LocalAuthStore, default as PocketBase, cookieParse, cookieSerialize, default, getTokenPayload, isTokenExpired, normalizeUnknownQueryParams } from 'pocketbase';
+export { AsyncAuthStore, core_default as Base, LocalAuthStore, cookieParse, cookieSerialize, core_default as default, getTokenPayload, isTokenExpired, normalizeUnknownQueryParams } from '../chunk-DC6LDHAD.js';
+export { BaseClient, ClientResponseError, MemoryAuthStore } from '../chunk-3WOGNODW.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/compat/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js","sourcesContent":[]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}