@nestcorehq/js 0.9.0 → 0.10.0

package/README.md

@@ -192,6 +192,45 @@ const { data } = await client.db.from('articles').eq('published', true).semantic
 
 See https://nestcore.io/docs/memory-api, /docs/collections, /docs/threads and /docs/embeddings.
 
+#### Your own embeddings, trust and batches
+
+Memory and collections also take vectors from your own (e.g. local) embedding model; the server then calls no provider and charges nothing. Search compares only vectors of the same `model` and size.
+
+```ts
+const model = 'nomic-embed-text-v1.5';
+await client.memory.add('Prefers tea', { embedding: vec, model, metadata: { trust: 'user' } });
+await client.memory.search({ queryEmbedding: q, model, trust: ['user', 'tool'] }); // text query optional
+
+// Batches: up to 100 adds, 20 searches, 500 ids / 20 subjects per call
+await client.memory.addMany([{ content: 'a', embedding: va, model }, { content: 'b', embedding: vb, model }]);
+const { data: batch } = await client.memory.searchMany([{ queryEmbedding: q1, model }, { query: 'tea' }]);
+await client.memory.forgetMany({ ids: ['…'], subjects: ['owner:…'] });
+
+// A collection document from chunks you embedded (ready at once; the first chunks fix the collection's model)
+await client.collections.from('notes').addChunks([{ content: 'Refunds take 5 days', embedding: v }], { model, title: 'FAQ' });
+await client.collections.from('notes').search({ queryEmbedding: q, model, trust: 'user' });
+```
+
+### AI credits and the OpenAI-compatible API
+
+A project's own provider key always wins. Without one, the workspace's prepaid AI credit can pay (bought in Console → Settings → Billing).
+
+```ts
+const { data: credits } = await client.ai.credits();
+// { available, active, balanceUsd, monthlyCapUsd, spentThisMonthUsd, ownKeys, creditProviders }
+
+try {
+  unwrap(await client.ai.chat({ messages }));
+} catch (e) {
+  if (e instanceof NestCoreError && e.isCreditsExhausted) {
+    // e.reason: 'balance' | 'spend_cap'. Don't retry: offer e.buyUrl, or adding your own key.
+  }
+}
+
+// Any OpenAI client works against the gateway (anon key as `apikey`, the user's token as the API key)
+new OpenAI({ baseURL: client.ai.openaiBaseUrl, apiKey: accessToken, defaultHeaders: { apikey: anonKey } });
+```
+
 ## Realtime
 
 Browsers can't set WebSocket request headers, so the API key is sent via the

package/dist/index.d.mts

@@ -1361,8 +1361,23 @@ interface AiMemoryMatch extends AiMemory {
     /** Similarity nudged by importance and recency; results are sorted by it. */
     score: number;
 }
-interface MemoryAddOptions {
-    /** Service key only: `type:id`, e.g. `user:<id>`, `agent:support`. Signed-in users are always `user:<their id>`. */
+/** `metadata.trust` (and the search `trust` filter): a lowercase word such as `user`, `tool` or `web`. */
+type AiTrust = string | string[];
+/**
+ * A vector you computed with your own (e.g. local) embedding model. The server
+ * then calls no model provider and charges nothing. Search compares only
+ * vectors of the same `model` and size, so switching models means re-sending.
+ */
+interface ClientEmbedding {
+    /** 1–2000 finite numbers, not all zeros. Needs `model`. */
+    embedding?: number[];
+    /** The model that produced the vector (names the vector space), e.g. `nomic-embed-text-v1.5`. */
+    model?: string;
+    /** Checked against the vector length. */
+    dims?: number;
+}
+interface MemoryAddOptions extends ClientEmbedding {
+    /** Service key only: `type:id`, e.g. `user:<id>`, `agent:support`. Signed-in users are always `user:<their id>`; device and phone tokens default to `owner:<owner id>`. */
     subject?: string;
     /** fact (default), preference, episode, summary, or your own word. */
     kind?: string;
@@ -1370,11 +1385,47 @@ interface MemoryAddOptions {
     importance?: number;
     /** ISO date; the memory is deleted after it. */
     expiresAt?: string | null;
+    /** `trust` is reserved: a lowercase word (`^[a-z][a-z0-9_-]{0,31}$`). */
     metadata?: Record<string, unknown>;
     sourceThreadId?: string;
     /** Update a near-identical memory (cosine ≥ 0.92) instead of adding one. Default true. */
     dedupe?: boolean;
 }
+/** One item of {@link MemoryClient.addMany}. */
+interface MemoryAddItem extends MemoryAddOptions {
+    content: string;
+}
+interface MemorySearchOptions {
+    subject?: string;
+    /** 1–50, default 5. */
+    k?: number;
+    kind?: string;
+    minSimilarity?: number;
+    /** Only memories whose `metadata.trust` is this word (or one of these words). */
+    trust?: AiTrust;
+    /** Your own query vector; `query` text is then optional. Needs `model`. */
+    queryEmbedding?: number[];
+    /** The model of `queryEmbedding`. */
+    model?: string;
+    dims?: number;
+}
+/** One query of {@link MemoryClient.searchMany}: `query` text, `queryEmbedding`, or both. */
+interface MemorySearchItem extends MemorySearchOptions {
+    query?: string;
+}
+interface MemorySearchResult {
+    results: AiMemoryMatch[];
+    /** true = the model provider was down and keyword search answered. */
+    degraded: boolean;
+    model: string | null;
+}
+interface MemoryUpdatePatch extends ClientEmbedding {
+    content?: string;
+    kind?: string;
+    importance?: number;
+    expiresAt?: string | null;
+    metadata?: Record<string, unknown>;
+}
 /**
  * Memory API: facts about a user (or an agent, an org…) with semantic search.
  * A signed-in user reads and writes only their own memory; the service key may
@@ -1383,27 +1434,48 @@ interface MemoryAddOptions {
  * ```ts
  * await client.memory.add('Prefers vegetarian recipes', { kind: 'preference' });
  * const { data } = await client.memory.search('what should I cook?');
+ *
+ * // Your own embeddings (no provider call, nothing charged):
+ * await client.memory.add('Prefers tea', { embedding: vec, model: 'nomic-embed-text-v1.5' });
+ * await client.memory.search({ queryEmbedding: q, model: 'nomic-embed-text-v1.5', trust: 'user' });
  * ```
  */
 declare class MemoryClient {
     private client;
     constructor(client: HttpClient);
     private path;
-    /** Remember something. `deduped: true` means an existing near-identical memory was updated. */
+    /**
+     * Remember something. `deduped: true` means an existing near-identical memory was updated.
+     * Pass `embedding` + `model` to use your own vector.
+     */
     add(content: string, options?: MemoryAddOptions): Promise<ApiResult<{
         memory: AiMemory;
         deduped: boolean;
     }>>;
-    /** Most relevant memories. `degraded: true` = the model provider was down and keyword search answered. */
-    search(query: string, options?: {
-        subject?: string;
-        k?: number;
-        kind?: string;
-        minSimilarity?: number;
+    /**
+     * Most relevant memories. `degraded: true` = the model provider was down and keyword search answered.
+     * With `queryEmbedding` + `model` the text is optional: `search({ queryEmbedding, model })`
+     * or `search(null, { queryEmbedding, model })`.
+     */
+    search(query: string | null | undefined, options?: MemorySearchOptions): Promise<ApiResult<MemorySearchResult>>;
+    search(options: MemorySearchItem): Promise<ApiResult<MemorySearchResult>>;
+    /** Up to 100 memories in one call (each counts against the memory quota). An invalid item fails the whole call with `400 "item <i>: …"`. */
+    addMany(items: MemoryAddItem[]): Promise<ApiResult<{
+        results: Array<{
+            memory: AiMemory;
+            deduped: boolean;
+        }>;
+    }>>;
+    /** Up to 20 searches in one call; `results[i]` answers `queries[i]`. */
+    searchMany(queries: MemorySearchItem[]): Promise<ApiResult<{
+        results: MemorySearchResult[];
+    }>>;
+    /** Delete memories by id (up to 500) and/or whole subjects (up to 20; users and agents only their own). */
+    forgetMany(target: {
+        ids?: string[];
+        subjects?: string[];
     }): Promise<ApiResult<{
-        results: AiMemoryMatch[];
-        degraded: boolean;
-        model: string | null;
+        deleted: number;
     }>>;
     list(options?: {
         subject?: string;
@@ -1415,13 +1487,8 @@ declare class MemoryClient {
         total: number;
     }>>;
     get(id: string): Promise<ApiResult<AiMemory>>;
-    update(id: string, patch: {
-        content?: string;
-        kind?: string;
-        importance?: number;
-        expiresAt?: string | null;
-        metadata?: Record<string, unknown>;
-    }): Promise<ApiResult<AiMemory>>;
+    /** `embedding` + `model` only together with new `content`. */
+    update(id: string, patch: MemoryUpdatePatch): Promise<ApiResult<AiMemory>>;
     remove(id: string): Promise<ApiResult<{
         deleted: boolean;
     }>>;
@@ -1509,6 +1576,38 @@ type DocumentSource = {
         path: string;
     };
 };
+/** A chunk you split and embedded yourself (see {@link CollectionRef.addChunks}). */
+interface ClientChunk {
+    content: string;
+    embedding: number[];
+    /** Chunk metadata, e.g. `{ trust: 'user' }`. */
+    metadata?: Record<string, unknown>;
+}
+interface AddChunksOptions {
+    /** The embedding model of every chunk. The first client chunks fix the collection's model; another model answers 409. */
+    model: string;
+    /** Checked against each vector's length. */
+    dims?: number;
+    title?: string;
+    metadata?: Record<string, unknown>;
+    /** Service key only: the user who owns (and alone can read) this document. */
+    ownerUserId?: string;
+}
+interface CollectionSearchOptions {
+    /** 1–50, default 8. */
+    k?: number;
+    /** Vector + keyword (default); `false` = vector only. */
+    hybrid?: boolean;
+    /** Documents whose metadata contains this object. */
+    filter?: Record<string, unknown>;
+    minSimilarity?: number;
+    /** Only chunks (or their document) whose `metadata.trust` is this word (or one of these words). */
+    trust?: AiTrust;
+    /** Your own query vector; `query` text is then optional. Needs `model` (the collection's). */
+    queryEmbedding?: number[];
+    model?: string;
+    dims?: number;
+}
 interface IngestOptions {
     title?: string;
     metadata?: Record<string, unknown>;
@@ -1531,17 +1630,30 @@ declare class CollectionRef {
      * text files are read from storage or a URL.
      */
     ingest(source: DocumentSource, options?: IngestOptions): Promise<ApiResult<AiDocument>>;
+    /**
+     * Add a document from chunks you embedded yourself (1–500; the body limit is 2 MB).
+     * It is `ready` at once; the server calls no provider and charges nothing.
+     *
+     * ```ts
+     * await kb.addChunks([{ content: 'Refunds take 5 days', embedding: vec }], { model: 'nomic-embed-text-v1.5', title: 'FAQ' });
+     * ```
+     */
+    addChunks(chunks: ClientChunk[], options: AddChunksOptions): Promise<ApiResult<AiDocument>>;
     /** Poll a document until it is `ready` or `failed`. */
     waitFor(documentId: string, { timeoutMs, intervalMs }?: {
         timeoutMs?: number;
         intervalMs?: number;
     }): Promise<ApiResult<AiDocument>>;
-    /** Hybrid search (vector + keyword). `hybrid: false` is vector only; `filter` matches document metadata. */
-    search(query: string, options?: {
-        k?: number;
-        hybrid?: boolean;
-        filter?: Record<string, unknown>;
-        minSimilarity?: number;
+    /**
+     * Hybrid search (vector + keyword). `hybrid: false` is vector only; `filter` matches document metadata.
+     * With your own vector: `search({ queryEmbedding, model })` or `search('text', { queryEmbedding, model })`.
+     */
+    search(query: string | null | undefined, options?: CollectionSearchOptions): Promise<ApiResult<{
+        results: AiSearchResult[];
+        model: string | null;
+    }>>;
+    search(options: CollectionSearchOptions & {
+        query?: string;
     }): Promise<ApiResult<{
         results: AiSearchResult[];
         model: string | null;
@@ -1695,6 +1807,7 @@ type ThreadRunEvent = {
     code?: string;
     message: string;
     status?: number;
+    details?: Record<string, unknown>;
 };
 interface ThreadRunResult {
     messageId: string;
@@ -1876,6 +1989,7 @@ type AiStreamEvent = {
     code?: string;
     message: string;
     status?: number;
+    details?: Record<string, unknown>;
 };
 interface AiEmbedResult {
     model: string;
@@ -1889,6 +2003,27 @@ interface AiModel {
     provider: AiProviderId;
     kind: 'chat' | 'embed';
     default?: boolean;
+    /** `credits`: paid from the workspace's prepaid AI credit (no project key for this provider). */
+    source?: 'credits';
+}
+/**
+ * Whether this project's AI calls can be paid from its workspace's prepaid
+ * credit (when the project has no key of its own for a provider). A project's
+ * own key always wins.
+ */
+interface AiCredits {
+    /** There is credit to spend now. */
+    available: boolean;
+    /** The workspace has bought credit at some point. */
+    active: boolean;
+    balanceUsd: number;
+    /** null = no monthly cap. */
+    monthlyCapUsd: number | null;
+    spentThisMonthUsd: number;
+    /** Providers the project has its own key for. */
+    ownKeys: AiProviderId[];
+    /** Providers the credit can pay for. */
+    creditProviders: AiProviderId[];
 }
 /**
  * AI Gateway: chat and embeddings through the project's own provider keys.
@@ -1907,6 +2042,16 @@ declare class AiClient {
     readonly threads: ThreadsClient;
     constructor(client: HttpClient);
     private path;
+    /**
+     * Base URL of the OpenAI-compatible API (`chat/completions` with `stream`,
+     * `embeddings`, `models`) for any OpenAI client. Send the project key as the
+     * `apikey` header and the user's (or device's) access token as the API key:
+     *
+     * ```ts
+     * new OpenAI({ baseURL: client.ai.openaiBaseUrl, apiKey: accessToken, defaultHeaders: { apikey: anonKey } });
+     * ```
+     */
+    get openaiBaseUrl(): string;
     private body;
     chat(options: AiChatOptions): Promise<ApiResult<AiChatResult>>;
     /**
@@ -1922,7 +2067,13 @@ declare class AiClient {
         model?: string;
         provider?: AiProviderId;
     }): Promise<ApiResult<AiEmbedResult>>;
-    /** Models the project can call with its saved provider keys. */
+    /**
+     * The workspace's prepaid AI credit as this project sees it. When a call is
+     * paid from credit and none is left, it fails with 402 `CREDITS_EXHAUSTED`
+     * (see `NestCoreError.isCreditsExhausted`, `reason` and `buyUrl`).
+     */
+    credits(): Promise<ApiResult<AiCredits>>;
+    /** Models the project can call with its saved provider keys (and, `source: 'credits'`, those its workspace's credit pays for). */
     models(): Promise<ApiResult<AiModel[]>>;
     /** Service key: per-call traces (model, tokens, latency, cost, status), newest first. */
     traces(options?: {
@@ -1980,10 +2131,30 @@ declare function sanitizePath(path: string): string;
 declare class NestCoreError extends Error {
     readonly code?: string;
     readonly status?: number;
+    /** The API's error body, e.g. QUOTA_EXCEEDED's `quota`/`plan`/`limit`/`upgradeUrl`. */
+    readonly details?: Record<string, unknown>;
     constructor(message: string, opts?: {
         code?: string;
         status?: number;
+        details?: Record<string, unknown>;
     });
+    /** 423: the project is paused (plan limit or owner) or compromised (kill switch). */
+    get isProjectPaused(): boolean;
+    /** 402 QUOTA_EXCEEDED: where to send the user to upgrade, when the API gave one. */
+    get upgradeUrl(): string | undefined;
+    /**
+     * 402: an AI call paid from the workspace's prepaid credit found none left
+     * (`reason` `balance`) or hit the monthly cap (`spend_cap`). Don't retry:
+     * offer `buyUrl`, or adding the project's own provider key.
+     */
+    get isCreditsExhausted(): boolean;
+    /**
+     * Why the call was refused, when the API said: `balance` | `spend_cap` for
+     * CREDITS_EXHAUSTED, the quota reason (e.g. `ai_collections`) for QUOTA_EXCEEDED.
+     */
+    get reason(): string | undefined;
+    /** 402 CREDITS_EXHAUSTED: where to buy more AI credit. */
+    get buyUrl(): string | undefined;
 }
 /** @deprecated Renamed to {@link NestCoreError}; kept so existing `instanceof` checks keep working. */
 declare const OrbitNestError: typeof NestCoreError;
@@ -2018,6 +2189,41 @@ declare const AuthLimitCodes: {
     /** Too many wrong passwords: the email is locked for the lockout duration. */
     readonly ACCOUNT_LOCKED: "ACCOUNT_LOCKED";
 };
+/**
+ * `error.code` values about the project itself (any endpoint can answer them).
+ * Project kinds: an App project is a backend for an app; an Agent project is
+ * the private backend of one PC running NestCore Agent.
+ */
+declare const ProjectErrorCodes: {
+    /**
+     * 402: a plan limit was reached. `details` has quota, plan, limit, usage and, for projects, kind/reason/upgradeUrl
+     * (`reason: 'ai_collections'` = the plan's collections per project).
+     */
+    readonly QUOTA_EXCEEDED: "QUOTA_EXCEEDED";
+    /**
+     * 402: an AI call paid from prepaid credit found none left. `details`: reason (`balance` | `spend_cap`),
+     * balanceUsd, monthlyCapUsd, spentThisMonthUsd, buyUrl. See {@link CreditsExhaustedDetails}.
+     */
+    readonly CREDITS_EXHAUSTED: "CREDITS_EXHAUSTED";
+    /** 423: the project is paused (downgrade or owner) or compromised (kill switch). Nothing was deleted. */
+    readonly PROJECT_PAUSED: "PROJECT_PAUSED";
+    /** 403: not allowed on an Agent project (only the agent schema, agent-* buckets and the agent functions). */
+    readonly AGENT_PROJECT_RESTRICTED: "AGENT_PROJECT_RESTRICTED";
+    /** 409: agent-only operation (agent template, agent functions) on an App project. */
+    readonly NOT_AN_AGENT_PROJECT: "NOT_AN_AGENT_PROJECT";
+};
+/** `balance`: no credit left; `spend_cap`: the workspace's monthly AI credit cap is reached. */
+type CreditsExhaustedReason = 'balance' | 'spend_cap';
+/** The body of a 402 `CREDITS_EXHAUSTED` (in `error.details` / `NestCoreError.details`). */
+interface CreditsExhaustedDetails {
+    code: 'CREDITS_EXHAUSTED';
+    reason: CreditsExhaustedReason;
+    message: string;
+    balanceUsd: number;
+    monthlyCapUsd: number | null;
+    spentThisMonthUsd: number;
+    buyUrl: string;
+}
 
 /** @deprecated Renamed to {@link NestCoreClient}. */
 type OrbitNestClient = NestCoreClient;
@@ -2085,4 +2291,4 @@ declare function createClient(config: NestCoreConfig & {
     storage?: StorageAdapter;
 }): NestCoreClient;
 
-export { type AiChatOptions, type AiChatResult, type AiCitation, AiClient, type AiCollection, type AiContentPart, type AiDocument, type AiEmbedResult, type AiMemory, type AiMemoryMatch, type AiMessage, type AiModel, type AiProviderId, type AiSearchResult, type AiStreamEvent, type AiThread, type AiThreadMessage, type AiThreadPart, type AiTool, type AiToolCall, type AiTrace, AnalyticsClient, type AnalyticsEvent, type AnalyticsOptions, type ApiError, type ApiResponse, type ApiResult, AuthClient, AuthLimitCodes, type AuthSession, type AuthUser, type BackgroundJob, type BackgroundJobRun, type BroadcastPayload, CollectionRef, CollectionsClient, type CreateJobOptions, DatabaseClient, type DocumentSource, EnvironmentClient, type EnvironmentVariable, type FilterValue, type FunctionInvokeOptions, type FunctionResponse, FunctionsClient, type GenerateTypesOptions, HttpClient, type ImageTransformOptions, type IngestOptions, type IngestionResult, JobsClient, type LogEntry, type LogQueryOptions, LoggingClient, type MemoryAddOptions, MemoryClient, type MfaChallenge, type MfaFactor, type NestCoreClient, type NestCoreConfig, NestCoreError, type OrbitNestClient, type OrbitNestConfig, OrbitNestError, type PaginationOptions, type PasskeyAuthenticateVerifyOptions, type PasskeyAuthenticationOptions, type PasskeyDevice, type PasskeyRegisterVerifyOptions, type PasskeyRegistrationOptions, type PasskeySignUpOptions, type PasskeySignUpVerifyOptions, type PasswordRecoveryOptions, type PasswordResetOptions, type PgChangesFilter, type PgChangesPayload, type PgEvent, type PresenceJoinCallback, type PresenceLeaveCallback, PresenceManager, type PresenceState, type PresenceSyncCallback, type QueryResult, RealtimeChannel, RealtimeClient, type RealtimeOptions, type RealtimeStatus, type RequestOptions, type RlsPolicy, type SignInCredentials, type SignUpCredentials, type StorageAdapter, StorageBucket, StorageClient, type StorageFile, type StorageListItem, type TableMetadata, ThreadRef, type ThreadRunEvent, type ThreadRunOptions, type ThreadRunResult, ThreadsClient, type UpdateJobOptions, type UpdateUserOptions, type UploadOptions, createClient, createLocalStorageAdapter, createMemoryAdapter, generateTypes, isMfaChallenge, localStorageAdapter, memoryAdapter, sanitizePath, unwrap, validatePath, validateRequired };
+export { type AddChunksOptions, type AiChatOptions, type AiChatResult, type AiCitation, AiClient, type AiCollection, type AiContentPart, type AiCredits, type AiDocument, type AiEmbedResult, type AiMemory, type AiMemoryMatch, type AiMessage, type AiModel, type AiProviderId, type AiSearchResult, type AiStreamEvent, type AiThread, type AiThreadMessage, type AiThreadPart, type AiTool, type AiToolCall, type AiTrace, type AiTrust, AnalyticsClient, type AnalyticsEvent, type AnalyticsOptions, type ApiError, type ApiResponse, type ApiResult, AuthClient, AuthLimitCodes, type AuthSession, type AuthUser, type BackgroundJob, type BackgroundJobRun, type BroadcastPayload, type ClientChunk, type ClientEmbedding, CollectionRef, type CollectionSearchOptions, CollectionsClient, type CreateJobOptions, type CreditsExhaustedDetails, type CreditsExhaustedReason, DatabaseClient, type DocumentSource, EnvironmentClient, type EnvironmentVariable, type FilterValue, type FunctionInvokeOptions, type FunctionResponse, FunctionsClient, type GenerateTypesOptions, HttpClient, type ImageTransformOptions, type IngestOptions, type IngestionResult, JobsClient, type LogEntry, type LogQueryOptions, LoggingClient, type MemoryAddItem, type MemoryAddOptions, MemoryClient, type MemorySearchItem, type MemorySearchOptions, type MemorySearchResult, type MemoryUpdatePatch, type MfaChallenge, type MfaFactor, type NestCoreClient, type NestCoreConfig, NestCoreError, type OrbitNestClient, type OrbitNestConfig, OrbitNestError, type PaginationOptions, type PasskeyAuthenticateVerifyOptions, type PasskeyAuthenticationOptions, type PasskeyDevice, type PasskeyRegisterVerifyOptions, type PasskeyRegistrationOptions, type PasskeySignUpOptions, type PasskeySignUpVerifyOptions, type PasswordRecoveryOptions, type PasswordResetOptions, type PgChangesFilter, type PgChangesPayload, type PgEvent, type PresenceJoinCallback, type PresenceLeaveCallback, PresenceManager, type PresenceState, type PresenceSyncCallback, ProjectErrorCodes, type QueryResult, RealtimeChannel, RealtimeClient, type RealtimeOptions, type RealtimeStatus, type RequestOptions, type RlsPolicy, type SignInCredentials, type SignUpCredentials, type StorageAdapter, StorageBucket, StorageClient, type StorageFile, type StorageListItem, type TableMetadata, ThreadRef, type ThreadRunEvent, type ThreadRunOptions, type ThreadRunResult, ThreadsClient, type UpdateJobOptions, type UpdateUserOptions, type UploadOptions, createClient, createLocalStorageAdapter, createMemoryAdapter, generateTypes, isMfaChallenge, localStorageAdapter, memoryAdapter, sanitizePath, unwrap, validatePath, validateRequired };