@aithos/sdk 0.1.0-alpha.4 → 0.1.0-alpha.40

package/dist/src/data.d.ts

@@ -0,0 +1,153 @@
+export interface AithosSchemaLite {
+    readonly schema: string;
+    readonly indexable: ReadonlySet<string>;
+    readonly encrypted: ReadonlySet<string>;
+    readonly auto: ReadonlySet<string>;
+    readonly defaults: Readonly<Record<string, unknown>>;
+}
+export interface CreateDataClientArgs {
+    /** Base URL of the deployed PDS (e.g. https://abc.execute-api.eu-west-3.amazonaws.com). */
+    readonly pdsUrl: string;
+    /** Subject DID — typically did:key:… in dev, did:aithos:… in prod. */
+    readonly did: string;
+    /**
+     * Ed25519 sphere seed (32 bytes). For did:key this is the same as
+     * the key embedded in the DID itself. For did:aithos this is the
+     * subject's `#data` (or `#public`) sphere key.
+     */
+    readonly sphereSeed: Uint8Array;
+    /**
+     * The verification method URL within the DID document used to sign
+     * envelopes. For did:key this is `<did>#<multibase>`. For did:aithos
+     * this is `<did>#data` (or `#public`).
+     */
+    readonly verificationMethod: string;
+    /** Optional fetch implementation. Defaults to globalThis.fetch. */
+    readonly fetch?: typeof fetch;
+    /**
+     * Optional list of app-defined schema definitions, in addition to
+     * the SDK-bundled core schemas (currently `aithos.contacts.v1`).
+     *
+     * Apps in the vendor namespace (`aithos.x.<vendor>.<name>.v<N>`) or
+     * non-`aithos.*` namespaces MUST supply their schemas here so the
+     * SDK can split records into indexable metadata vs encrypted payload.
+     *
+     * When the same schema id appears in both the bundled core registry
+     * and this list, the app-supplied definition wins (intentional —
+     * allows local overrides for testing, though immutability per spec
+     * §3.5 means a published schema id should never change shape).
+     *
+     * Schemas are scoped to the {@link DataClient} instance — they don't
+     * leak to other clients in the same process.
+     */
+    readonly schemas?: readonly AithosSchemaLite[];
+}
+export interface DataClient {
+    /** Get / create a collection handle. */
+    collection(name: string): DataCollection;
+    /** Initialize a new collection with an explicit schema. */
+    createCollection(args: {
+        name: string;
+        schema: string;
+        forwardSecrecy?: "best_effort" | "strict";
+    }): Promise<void>;
+    /** List collections owned by this subject. */
+    listCollections(): Promise<readonly {
+        name: string;
+        schema: string;
+        record_count: number;
+    }[]>;
+    /** List gamma audit entries. */
+    listGammaEntries(opts?: {
+        limit?: number;
+        opPrefix?: string;
+        verify?: boolean;
+    }): Promise<unknown>;
+    /**
+     * Idempotently publish a vendor (`aithos.x.<vendor>.<name>.v<N>`)
+     * JSON Schema document to this subject's PDS. Once published, the
+     * PDS validates record writes against the schema doc server-side,
+     * closing the gap A2a left open (cf. Aithos-protocol/PLAN-A2b-…).
+     *
+     * Safe to call on every app boot — re-registering the same document
+     * (same canonical hash) resolves to `{ created: false }`. A different
+     * document for the same `aithos:schema` id is REJECTED with code
+     * -32082 `AITHOS_DATA_SCHEMA_IMMUTABLE` ; the caller must bump the
+     * version segment in `aithos:schema` and retry.
+     *
+     * Core schemas (`aithos.<name>.v<N>` without `.x.`) cannot be
+     * registered via this RPC ; they're bundled by the platform per spec
+     * §3.7.2.
+     *
+     * @param schemaDoc Full JSON Schema 2020-12 document. MUST carry
+     *   `aithos:schema` and `aithos:version` top-level fields.
+     */
+    registerSchema(schemaDoc: object): Promise<{
+        schemaId: string;
+        docHash: string;
+        created: boolean;
+        createdAt?: string;
+    }>;
+    /**
+     * Fetch a published schema document from the PDS.
+     *
+     * For core schemas (`aithos.<name>.v<N>`) the lookup is global ;
+     * `subjectDid` is ignored. For vendor schemas (`aithos.x.*`) the
+     * `subjectDid` arg selects whose published registry to query and
+     * defaults to this client's own DID.
+     *
+     * Returns null when the lookup misses (rather than throwing) so
+     * call sites can branch on the result.
+     */
+    getSchema(schemaId: string, opts?: {
+        subjectDid?: string;
+    }): Promise<object | null>;
+    /** Drop in-memory cache (CMK, collection metadata, …). */
+    reset(): void;
+}
+export interface DataCollection {
+    readonly name: string;
+    /**
+     * Insert a record. The object MAY contain both indexable and
+     * encrypted fields per the schema; the SDK splits them.
+     */
+    insert(record: Record<string, unknown>): Promise<string>;
+    /** Fetch one record by id (decrypted client-side). */
+    get(recordId: string): Promise<Record<string, unknown> | null>;
+    /** List records, decrypted. Pagination via opaque cursor. */
+    list(opts?: ListOpts): Promise<{
+        items: Record<string, unknown>[];
+        nextCursor?: string;
+    }>;
+    /**
+     * Replace a record. Same shape as insert; the SDK splits indexable
+     * vs encrypted again per the schema.
+     */
+    update(recordId: string, record: Record<string, unknown>): Promise<void>;
+    /** Soft-delete a record. */
+    delete(recordId: string): Promise<void>;
+}
+export interface ListOpts {
+    readonly filter?: {
+        readonly equals?: {
+            field: string;
+            value: unknown;
+        };
+        readonly contains?: {
+            field: string;
+            value: string;
+        };
+        readonly tagsAny?: readonly string[];
+        readonly tagsAll?: readonly string[];
+        readonly range?: {
+            field: string;
+            gte?: string;
+            lte?: string;
+        };
+    };
+    readonly order?: "newest" | "oldest";
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+export declare function createDataClient(args: CreateDataClientArgs): DataClient;
+//# sourceMappingURL=data.d.ts.map