better-supabase 0.13.0 → 0.14.0

package/dist/connector-BdCE4Efp.d.ts

@@ -0,0 +1,164 @@
+import { b as DbError, f as Result, x as DbErrorKind } from "./result-C6jDfedy.js";
+//#region src/powersync/connector.d.ts
+/** A queued local change: PowerSync's `CrudEntry`. */
+interface CrudEntryLike {
+  /** `PUT`, `PATCH` or `DELETE` (PowerSync's `UpdateType`). */
+  readonly op: string;
+  readonly table: string;
+  readonly id: string;
+  readonly opData?: Readonly<Record<string, unknown>> | undefined;
+}
+/** The part of a PowerSync database the connector reads the queue from. */
+interface CrudQueueLike {
+  getCrudBatch(limit?: number): Promise<{
+    readonly crud: readonly CrudEntryLike[];
+    complete(): Promise<void>;
+  } | null>;
+}
+/**
+ * A repository a table's changes replay through (`bs.db.customers`), so RLS,
+ * plugins and validation run as they do online. `I` is the table's insert type
+ * and `K` its primary key; every generated repository fits.
+ */
+interface UploadRepository<I = Record<string, unknown>, K = string> {
+  upsert(data: I): PromiseLike<Result<unknown>>;
+  update(id: K, patch: Partial<I>): PromiseLike<Result<unknown>>;
+  delete(id: K): PromiseLike<Result<unknown>>;
+}
+/**
+ * A repository for a table whose rows are written once (attachments, events): a
+ * `PUT` inserts with `create`, and a `DELETE` calls `delete`.
+ */
+interface CreateUploadRepository<I = Record<string, unknown>, K = string> {
+  create(data: I): PromiseLike<Result<unknown>>;
+  delete(id: K): PromiseLike<Result<unknown>>;
+}
+/** Replays one queued change. */
+type UploadFunction = (entry: CrudEntryLike) => PromiseLike<Result<unknown>>;
+/** A table's route: its repository, or a function for custom replay. */
+type UploadRoute<I = Record<string, unknown>, K = string> = UploadRepository<I, K> | UploadFunction;
+interface UploadRouteOptions<P extends "upsert" | "create"> {
+  /**
+   * What a `PUT` calls. `upsert` (the default) inserts or replaces the row.
+   * `create` inserts it and counts a `conflict` as applied, since the row is
+   * already on the server (an earlier upload of the same change); a `PATCH`
+   * then fails with `unsupported` and is discarded.
+   */
+  readonly put?: P;
+}
+/** What an upload error means for the queued change. */
+type UploadOutcome = "retry" | "conflict" | "discard";
+/** A change the server refused, kept for the UI. */
+interface RejectedChange {
+  readonly entry: CrudEntryLike;
+  readonly error: DbError;
+  readonly outcome: "conflict" | "discard";
+}
+/** A `useSyncExternalStore`-compatible list of refused changes. */
+interface RejectedStore {
+  readonly current: () => readonly RejectedChange[];
+  readonly subscribe: (listener: () => void) => () => void;
+  /** Forgets one change, or all of them. */
+  readonly dismiss: (change?: RejectedChange) => void;
+}
+interface SessionClient {
+  readonly auth: {
+    getSession(): Promise<{
+      readonly data: {
+        readonly session: {
+          readonly access_token: string;
+          readonly expires_at?: number | undefined;
+        } | null;
+      };
+      readonly error?: {
+        readonly name?: string;
+        readonly message: string;
+      } | null;
+    }>;
+  };
+}
+/** Where the connector met an error it reports to `onError`. */
+interface UploadErrorContext {
+  /**
+   * `credentials`: reading the Supabase session failed, so sync and uploads
+   * wait for PowerSync's next try. `upload`: a change failed with an error that
+   * keeps the batch queued for a retry.
+   */
+  readonly phase: "credentials" | "upload";
+}
+interface UploadConnectorOptions {
+  /** The PowerSync service URL. */
+  readonly endpoint: string;
+  /** The supabase-js client whose session authenticates sync and uploads. */
+  readonly supabase: SessionClient;
+  /** Every synced table that takes local writes, by its SQLite name. */
+  readonly tables: Readonly<Record<string, UploadRoute>>;
+  /** Changes per upload batch. Defaults to 100. */
+  readonly batchSize?: number;
+  /** Overrides `uploadOutcome` for some errors. */
+  readonly classify?: (error: DbError, entry: CrudEntryLike) => UploadOutcome | undefined;
+  readonly onConflict?: (change: RejectedChange) => void;
+  readonly onDiscard?: (change: RejectedChange) => void;
+  /**
+   * Called when reading the session fails (kind `unauthorized`, or `network`
+   * when the Auth server is unreachable) and when an upload error keeps the
+   * batch queued. PowerSync retries both on its own; this is for logging. A
+   * signed-out session is not an error.
+   */
+  readonly onError?: (error: DbError, context: UploadErrorContext) => void;
+}
+/** PowerSync's `PowerSyncBackendConnector`. */
+interface UploadConnector {
+  fetchCredentials(): Promise<{
+    readonly endpoint: string;
+    readonly token: string;
+    readonly expiresAt?: Date;
+  } | null>;
+  uploadData(database: CrudQueueLike): Promise<void>;
+  /** Changes the server refused since the app started. */
+  readonly rejected: RejectedStore;
+}
+/**
+ * The default for a failed upload: transient errors retry, a newer server row
+ * is a conflict, and a change the server will never accept is discarded so it
+ * doesn't block the queue.
+ */
+declare function uploadOutcome(kind: DbErrorKind): UploadOutcome;
+/**
+ * Turns a repository into a function route. By default a `PUT` upserts, a
+ * `PATCH` updates and a `DELETE` deletes, as a bare repository in `tables`
+ * does. With `put: "create"`, a `PUT` inserts and a `conflict` counts as
+ * applied, for tables whose rows are written once.
+ *
+ * ```ts
+ * tables: {
+ *   customers: bs.db.customers,
+ *   attachments: uploadRoute(bs.db.attachments, { put: "create" }),
+ * }
+ * ```
+ */
+declare function uploadRoute<I, K>(repository: CreateUploadRepository<I, K>, options: UploadRouteOptions<"create"> & {
+  readonly put: "create";
+}): UploadFunction;
+declare function uploadRoute<I, K>(repository: UploadRepository<I, K>, options?: UploadRouteOptions<"upsert">): UploadFunction;
+/**
+ * A PowerSync connector that authenticates with the Supabase session and
+ * replays queued changes through repositories. Changes upload in batches; a
+ * transient error keeps the batch queued for PowerSync's retry, and refused
+ * changes land in `rejected` instead of blocking the queue. A table without a
+ * route stops the upload with an error, so no change is dropped silently. When
+ * the session is gone (the refresh token was revoked), the upload stops until
+ * the user signs in again.
+ *
+ * ```ts
+ * const connector = createUploadConnector({
+ *   endpoint: process.env.EXPO_PUBLIC_POWERSYNC_URL,
+ *   supabase,
+ *   tables: { customers: bs.db.customers },
+ * });
+ * await powersync.connect(connector);
+ * ```
+ */
+declare function createUploadConnector(options: UploadConnectorOptions): UploadConnector;
+//#endregion
+export { RejectedStore as a, UploadErrorContext as c, UploadRepository as d, UploadRoute as f, uploadRoute as g, uploadOutcome as h, RejectedChange as i, UploadFunction as l, createUploadConnector as m, CrudEntryLike as n, UploadConnector as o, UploadRouteOptions as p, CrudQueueLike as r, UploadConnectorOptions as s, CreateUploadRepository as t, UploadOutcome as u };

package/dist/connectors-DDiSNvkF.d.ts

@@ -0,0 +1,147 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, t as AsyncResult } from "./result-C6jDfedy.js";
+import { t as StandardSchemaV1 } from "./standard-DbQsD2xZ.js";
+import { n as ExtraFields, r as FieldsOf } from "./block-fields-3w4MZr8U.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { i as CredentialRef, r as CredentialProvider } from "./provider-DmiaI1qt.js";
+import { r as BlockTemporalOptions } from "./block-helpers-BaugZlJV.js";
+import { t as BlockTransport } from "./block-transport-d53POsem.js";
+import { n as BlockHooks } from "./block-hooks-CmjPKqQ_.js";
+//#region src/blocks/connectors/connectors.d.ts
+type ConnectorTransport = "http" | "sse";
+/**
+ * `none`, OAuth per user (a grant each), or a header from the server's
+ * credential_ref.
+ */
+type ConnectorAuth = "none" | "oauth" | "header";
+type FingerprintStatus = "approved" | "pending" | "rejected";
+interface ConnectorGrant {
+  readonly id: string;
+  readonly userId: string;
+  readonly serverId: string;
+  readonly organizationId: string;
+  readonly credentialRef: CredentialRef;
+  readonly scopes: readonly string[];
+  readonly expiresAt: Temporal.Instant | undefined;
+  readonly grantedAt: Temporal.Instant;
+  readonly revokedAt: Temporal.Instant | undefined;
+}
+/** An MCP server. `F` types the extra columns the `fields` schema describes. */
+interface ConnectorServer<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly name: string;
+  readonly url: string;
+  readonly transport: ConnectorTransport;
+  readonly authType: ConnectorAuth;
+  /** For `header` auth: the app credential sent with every request. */
+  readonly credentialRef: CredentialRef | undefined;
+  /** The OAuth scopes to ask for. */
+  readonly scopes: readonly string[];
+  /** OAuth client metadata for dynamic client registration. */
+  readonly clientMetadata: Readonly<Record<string, unknown>>;
+  readonly enabled: boolean;
+  /** The caller's (or `ownerId`'s) active grant, from `list` and `get`. */
+  readonly grant: ConnectorGrant | undefined;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+}
+interface ConnectorServerFields<F extends object = Record<never, never>> {
+  readonly name?: string;
+  readonly url?: string;
+  readonly transport?: ConnectorTransport;
+  readonly authType?: ConnectorAuth;
+  readonly credentialRef?: CredentialRef | null;
+  readonly scopes?: readonly string[];
+  readonly clientMetadata?: Readonly<Record<string, unknown>>;
+  readonly enabled?: boolean;
+  /** The extra columns to set, keyed by database name; others keep their value. */
+  readonly fields?: Partial<F>;
+}
+interface ConnectorSession {
+  readonly sessionId: string | undefined;
+  readonly initializeResult: Readonly<Record<string, unknown>> | undefined;
+  readonly expiresAt: Temporal.Instant;
+}
+interface ConnectorsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  /**
+   * A Standard Schema for the server's extra columns
+   * (`blocks.connectors.options.extraColumns`), keyed by database name. It
+   * types and parses them on reads, and validates them on `create` and
+   * `update`.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Connectors<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  /** Calls as the user: `rpcTransport(supabase)`. */
+  readonly transport: BlockTransport;
+  /** Calls as the service role, for grants and renewals. */
+  readonly service?: BlockTransport;
+  /**
+   * The module schema, or its API schema: `defineBlocks` passes it from
+   * `blocks.generated.ts`. Default `better_supabase`.
+   */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /** Revokes a grant's credential when the grant or its server goes away. */
+  readonly credentials?: CredentialProvider;
+}
+/** `F` is the extra fields `options.fields` describes. */
+interface Connectors<F extends object = Record<never, never>> {
+  readonly servers: {
+    list(organizationId: string): AsyncResult<readonly ConnectorServer<F>[]>;
+    /** With `ownerId` (service role), the grant is that user's. */
+    get(serverId: string, options?: {
+      readonly ownerId?: string;
+    }): AsyncResult<ConnectorServer<F>>;
+    create(organizationId: string, server: ConnectorServerFields<F> & {
+      readonly name: string;
+      readonly url: string;
+    }): AsyncResult<ConnectorServer<F>>;
+    update(organizationId: string, serverId: string, fields: ConnectorServerFields<F>): AsyncResult<ConnectorServer<F>>;
+    /** Deletes a server and revokes its grants' credentials. Returns how many. */
+    remove(serverId: string): AsyncResult<number>;
+  };
+  readonly grants: {
+    /**
+     * Records a user's grant after the provider stored the credential (service
+     * role), revoking the grant it replaces.
+     */
+    record(serverId: string, userId: string, credentialRef: CredentialRef, options?: {
+      readonly scopes?: readonly string[];
+      readonly expiresAt?: Temporal.Instant;
+    }): AsyncResult<ConnectorGrant>;
+    /** Revokes a grant (its owner or the service role) and its credential. */
+    revoke(grantId: string): AsyncResult<boolean>;
+    /** Active grants expiring before `before` (service role). */
+    expiring(before: Temporal.Instant, options?: {
+      readonly limit?: number;
+    }): AsyncResult<readonly ConnectorGrant[]>;
+    renew(grantId: string, expiresAt: Temporal.Instant): AsyncResult<boolean>;
+  };
+  readonly sessions: {
+    get(serverId: string, chatKey?: string): AsyncResult<ConnectorSession | undefined>;
+    save(serverId: string, session: {
+      readonly chatKey?: string;
+      readonly sessionId?: string;
+      readonly initializeResult?: Readonly<Record<string, unknown>>;
+    }): AsyncResult<boolean>;
+    forget(serverId: string, chatKey?: string): AsyncResult<boolean>;
+    /** Deletes expired sessions (service role). */
+    purge(): AsyncResult<number>;
+  };
+  readonly fingerprints: {
+    /** Records a tool list's fingerprint and returns whether it may be called. */
+    check(serverId: string, fingerprint: string, tools?: Readonly<Record<string, unknown>>): AsyncResult<FingerprintStatus>;
+    approve(serverId: string, fingerprint: string): AsyncResult<boolean>;
+    reject(serverId: string, fingerprint: string): AsyncResult<boolean>;
+  };
+}
+/** MCP servers, per-user grants, sessions and tool list fingerprints. */
+declare function createConnectors<S extends StandardSchemaV1 | undefined = undefined>(options: ConnectorsOptions<S>): Connectors<FieldsOf<S>>;
+//#endregion
+export { ConnectorSession as a, ConnectorsOptions as c, ConnectorServerFields as i, FingerprintStatus as l, ConnectorGrant as n, ConnectorTransport as o, ConnectorServer as r, Connectors as s, ConnectorAuth as t, createConnectors as u };