@ai-matrx/records 0.87.31 → 0.92.0

package/dist/setup/index.d.cts

@@ -0,0 +1,87 @@
+import { RealtimeManager } from '@ai-matrx/realtime';
+import { R as RecordsClient } from '../client-DE9Mq6YX.cjs';
+import { C as CreateEntityDataPortOptions, E as EntityDataPort } from '../port-CPVBfDxS.cjs';
+import { a as RecordsConfig, b as RecordsErrorSink, c as RecordsDataSource, d as RecordsChangeSink } from '../ports-DSU2RsR6.cjs';
+import { U as Uuid, R as RecordsResult } from '../record-BQi92d4-.cjs';
+import { RecordSearchRequest, RecordSearchHit, listStoreRecordCandidates } from '../search/index.cjs';
+import '../table-kind-Cm6PXkWx.cjs';
+import '../field-BJBnTyJ0.cjs';
+import '../subscription-D-VEzvyy.cjs';
+import '../rule-BMViCLmW.cjs';
+import '../relation-DMwkmzgN.cjs';
+import '../portal-DfeY2Boy.cjs';
+import '../types-DTEGaxso.cjs';
+
+/** A signed-in database identity: the client every door and live change rides, and who it is. */
+interface RecordsSession {
+    /** A supabase-js client (or anything shaped like one) carrying the identity's access token. */
+    supabase: object;
+    /** The identity's user id, when known (the live-change echo test and the client's own mirror use it). */
+    userId?: Uuid;
+}
+/** How setup signs in. Session today; an organization API key later — same port. */
+interface RecordsAuthPort {
+    readonly kind: "session" | "api_key";
+    session(): Promise<RecordsSession>;
+}
+/** A supabase-js client that already carries a signed-in person (browser sign-in, `signInWithPassword`, SSR cookies). */
+declare function sessionAuth(supabase: object, userId?: Uuid): RecordsAuthPort;
+interface CreateRecordsOptions<TAssociations = never> {
+    auth: RecordsAuthPort;
+    /**
+     * Where new things are saved and which organization a write runs in. `null` = no writes, reads across
+     * all. A function receives every organization the identity belongs to and answers the host's choice.
+     */
+    organizationId: Uuid | null | ((organizationIds: readonly Uuid[]) => Uuid | null);
+    /** Who is acting. Default: the signed-in person (`user`). An agent acting for a person names `on_behalf_of`. */
+    actor?: RecordsConfig["actor"];
+    /**
+     * Live changes. Default `true`: one realtime manager over the session's client. Pass your own
+     * `RealtimeManager` to share a socket, or `false` for none (`watch` then says so and returns a no-op).
+     */
+    live?: boolean | RealtimeManager;
+    /**
+     * Platform-record aliases (`{ contacts: { kind: "entity", token: "party" } }`) for `entities`. Optional.
+     */
+    entityAliases?: CreateEntityDataPortOptions["aliases"];
+    /** The associations store (`@ai-matrx/associations/core` `createAssociationsStore`) bound by the host; handed back as-is. */
+    associations?: TAssociations;
+    onError?: RecordsErrorSink;
+}
+interface RecordsSetup<TAssociations = never> {
+    /** How this setup signed in. */
+    readonly authKind: RecordsAuthPort["kind"];
+    /** The signed-in identity's user id, when known. */
+    readonly userId: Uuid | undefined;
+    /** Every organization the identity belongs to (reads span them; the host filters visibly). */
+    readonly organizationIds: readonly Uuid[];
+    /** Where this setup's writes go (the host's choice), or null. */
+    readonly organizationId: Uuid | null;
+    /** The typed client over the store's doors: tables, records, versions, archive and restore, views, forms… */
+    readonly records: RecordsClient;
+    /** The data source the doors ride — hand it to any other section (`records/forms`, `records/search`). */
+    readonly dataSource: RecordsDataSource;
+    /** Platform records (contacts, projects, tasks) through the same port shape custom tables use. */
+    readonly entities: EntityDataPort;
+    /** The live-changes manager, or null when `live: false`. */
+    readonly realtime: RealtimeManager | null;
+    /** Search every table the identity can see (never narrowed by `organizationId`). */
+    search(request: RecordSearchRequest): Promise<RecordsResult<RecordSearchHit[]>>;
+    /** Candidates for a "link a record" picker. */
+    recordCandidates(args: {
+        search?: string;
+        limit?: number;
+    }): ReturnType<typeof listStoreRecordCandidates>;
+    /**
+     * Watch one table's records (other people's changes; this setup's own writes are dropped). `records(ids)`
+     * names the changed records (`null` = re-read the page); `shape()` = the table's columns moved.
+     */
+    watch(tableId: Uuid, sink: Partial<RecordsChangeSink>, organizationId?: Uuid): () => void;
+    /** The associations store the host bound, if any. */
+    readonly associations: TAssociations | undefined;
+    /** Close live channels (a Node script calls this before it exits). */
+    close(): void;
+}
+declare function createRecords<TAssociations = never>(options: CreateRecordsOptions<TAssociations>): Promise<RecordsSetup<TAssociations>>;
+
+export { type CreateRecordsOptions, type RecordsAuthPort, type RecordsSession, type RecordsSetup, createRecords, sessionAuth };

package/dist/setup/index.d.ts

@@ -0,0 +1,87 @@
+import { RealtimeManager } from '@ai-matrx/realtime';
+import { R as RecordsClient } from '../client-vJAb7g9r.js';
+import { C as CreateEntityDataPortOptions, E as EntityDataPort } from '../port-D2i2o7Lg.js';
+import { a as RecordsConfig, b as RecordsErrorSink, c as RecordsDataSource, d as RecordsChangeSink } from '../ports-BWtxAnXh.js';
+import { U as Uuid, R as RecordsResult } from '../record-BQi92d4-.js';
+import { RecordSearchRequest, RecordSearchHit, listStoreRecordCandidates } from '../search/index.js';
+import '../table-kind-CVp43g6h.js';
+import '../field-Ti5iAxFr.js';
+import '../subscription-5CLN3Jug.js';
+import '../rule-B8kR0l01.js';
+import '../relation-DlcqV_W5.js';
+import '../portal-Db4CYyHe.js';
+import '../types-Dji5SpFS.js';
+
+/** A signed-in database identity: the client every door and live change rides, and who it is. */
+interface RecordsSession {
+    /** A supabase-js client (or anything shaped like one) carrying the identity's access token. */
+    supabase: object;
+    /** The identity's user id, when known (the live-change echo test and the client's own mirror use it). */
+    userId?: Uuid;
+}
+/** How setup signs in. Session today; an organization API key later — same port. */
+interface RecordsAuthPort {
+    readonly kind: "session" | "api_key";
+    session(): Promise<RecordsSession>;
+}
+/** A supabase-js client that already carries a signed-in person (browser sign-in, `signInWithPassword`, SSR cookies). */
+declare function sessionAuth(supabase: object, userId?: Uuid): RecordsAuthPort;
+interface CreateRecordsOptions<TAssociations = never> {
+    auth: RecordsAuthPort;
+    /**
+     * Where new things are saved and which organization a write runs in. `null` = no writes, reads across
+     * all. A function receives every organization the identity belongs to and answers the host's choice.
+     */
+    organizationId: Uuid | null | ((organizationIds: readonly Uuid[]) => Uuid | null);
+    /** Who is acting. Default: the signed-in person (`user`). An agent acting for a person names `on_behalf_of`. */
+    actor?: RecordsConfig["actor"];
+    /**
+     * Live changes. Default `true`: one realtime manager over the session's client. Pass your own
+     * `RealtimeManager` to share a socket, or `false` for none (`watch` then says so and returns a no-op).
+     */
+    live?: boolean | RealtimeManager;
+    /**
+     * Platform-record aliases (`{ contacts: { kind: "entity", token: "party" } }`) for `entities`. Optional.
+     */
+    entityAliases?: CreateEntityDataPortOptions["aliases"];
+    /** The associations store (`@ai-matrx/associations/core` `createAssociationsStore`) bound by the host; handed back as-is. */
+    associations?: TAssociations;
+    onError?: RecordsErrorSink;
+}
+interface RecordsSetup<TAssociations = never> {
+    /** How this setup signed in. */
+    readonly authKind: RecordsAuthPort["kind"];
+    /** The signed-in identity's user id, when known. */
+    readonly userId: Uuid | undefined;
+    /** Every organization the identity belongs to (reads span them; the host filters visibly). */
+    readonly organizationIds: readonly Uuid[];
+    /** Where this setup's writes go (the host's choice), or null. */
+    readonly organizationId: Uuid | null;
+    /** The typed client over the store's doors: tables, records, versions, archive and restore, views, forms… */
+    readonly records: RecordsClient;
+    /** The data source the doors ride — hand it to any other section (`records/forms`, `records/search`). */
+    readonly dataSource: RecordsDataSource;
+    /** Platform records (contacts, projects, tasks) through the same port shape custom tables use. */
+    readonly entities: EntityDataPort;
+    /** The live-changes manager, or null when `live: false`. */
+    readonly realtime: RealtimeManager | null;
+    /** Search every table the identity can see (never narrowed by `organizationId`). */
+    search(request: RecordSearchRequest): Promise<RecordsResult<RecordSearchHit[]>>;
+    /** Candidates for a "link a record" picker. */
+    recordCandidates(args: {
+        search?: string;
+        limit?: number;
+    }): ReturnType<typeof listStoreRecordCandidates>;
+    /**
+     * Watch one table's records (other people's changes; this setup's own writes are dropped). `records(ids)`
+     * names the changed records (`null` = re-read the page); `shape()` = the table's columns moved.
+     */
+    watch(tableId: Uuid, sink: Partial<RecordsChangeSink>, organizationId?: Uuid): () => void;
+    /** The associations store the host bound, if any. */
+    readonly associations: TAssociations | undefined;
+    /** Close live channels (a Node script calls this before it exits). */
+    close(): void;
+}
+declare function createRecords<TAssociations = never>(options: CreateRecordsOptions<TAssociations>): Promise<RecordsSetup<TAssociations>>;
+
+export { type CreateRecordsOptions, type RecordsAuthPort, type RecordsSession, type RecordsSetup, createRecords, sessionAuth };