@loams/client 0.1.0 → 0.1.1

package/dist/gen/facade.js

@@ -14,8 +14,12 @@
 export const PROTO_REV = 'v1';
 import { AgentService, AuditService, KeyService, OrgService, ProjectService } from '../vendor/proto/admin.js';
 import { AuthService } from '../vendor/proto/gen/loams/auth/v1/auth_pb.js';
+import { CollectionService, DocumentService, NamespaceService, QueryService } from '../vendor/proto/collection-v1.js';
+import { GraphAdminService, GraphService } from '../vendor/proto/gen/loams/graph/v1/graph_pb.js';
 import { InstanceService } from '../vendor/proto/gen/loams/instance/v1/instance_pb.js';
 import { LiveAdminService, LiveService } from '@loams/live/live';
+import { SqlService } from '../vendor/proto/gen/loams/sql/v1/sql_pb.js';
+import { StreamService } from '../vendor/proto/gen/loams/stream/v1/stream_pb.js';
 /** Every annotated service, as the module catalogue. Order is by module name. */
 export const MODULES = [
     {
@@ -120,6 +124,62 @@ export const MODULES = [
             { module: 'auth', name: 'listProviders', protoName: 'listProviders', method: 'ListProviders', rpc: 'loams.auth.v1.AuthService/ListProviders', service: 'loams.auth.v1.AuthService', package: 'loams.auth.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: null },
         ],
     },
+    {
+        name: 'collections',
+        summary: 'Collections: schema, aliases, versions, scan plans and the hot tier.',
+        service: 'loams.collection.v1.CollectionService',
+        package: 'loams.collection.v1',
+        unstable: false,
+        derived: false,
+        calls: [
+            { module: 'collections', name: 'addFields', protoName: 'add_fields', method: 'AddFields', rpc: 'loams.collection.v1.CollectionService/AddFields', service: 'loams.collection.v1.CollectionService', package: 'loams.collection.v1', idempotency: 'none', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'collections', name: 'create', protoName: 'create', method: 'CreateCollection', rpc: 'loams.collection.v1.CollectionService/CreateCollection', service: 'loams.collection.v1.CollectionService', package: 'loams.collection.v1', idempotency: 'none', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'collections', name: 'drop', protoName: 'drop', method: 'DropCollection', rpc: 'loams.collection.v1.CollectionService/DropCollection', service: 'loams.collection.v1.CollectionService', package: 'loams.collection.v1', idempotency: 'none', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'collections', name: 'get', protoName: 'get', method: 'GetCollection', rpc: 'loams.collection.v1.CollectionService/GetCollection', service: 'loams.collection.v1.CollectionService', package: 'loams.collection.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'collections', name: 'list', protoName: 'list', method: 'ListCollections', rpc: 'loams.collection.v1.CollectionService/ListCollections', service: 'loams.collection.v1.CollectionService', package: 'loams.collection.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: { items: 'collections', nextPageToken: 'nextPageToken' } },
+            { module: 'collections', name: 'listVersions', protoName: 'list_versions', method: 'ListVersions', rpc: 'loams.collection.v1.CollectionService/ListVersions', service: 'loams.collection.v1.CollectionService', package: 'loams.collection.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: { items: 'versions', nextPageToken: 'nextPageToken' } },
+            { module: 'collections', name: 'scan', protoName: 'scan', method: 'Scan', rpc: 'loams.collection.v1.CollectionService/Scan', service: 'loams.collection.v1.CollectionService', package: 'loams.collection.v1', idempotency: 'none', retry: 'manual', streaming: 'unary', pagination: null },
+            { module: 'collections', name: 'setHot', protoName: 'set_hot', method: 'SetHot', rpc: 'loams.collection.v1.CollectionService/SetHot', service: 'loams.collection.v1.CollectionService', package: 'loams.collection.v1', idempotency: 'none', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'collections', name: 'updateAliases', protoName: 'update_aliases', method: 'UpdateAliases', rpc: 'loams.collection.v1.CollectionService/UpdateAliases', service: 'loams.collection.v1.CollectionService', package: 'loams.collection.v1', idempotency: 'none', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'collections', name: 'warm', protoName: 'warm', method: 'WarmCollection', rpc: 'loams.collection.v1.CollectionService/WarmCollection', service: 'loams.collection.v1.CollectionService', package: 'loams.collection.v1', idempotency: 'none', retry: 'safe', streaming: 'unary', pagination: null },
+        ],
+    },
+    {
+        name: 'documents',
+        summary: 'Documents: write, get, scroll, count, delete by filter and patch by filter.',
+        service: 'loams.collection.v1.DocumentService',
+        package: 'loams.collection.v1',
+        unstable: false,
+        derived: false,
+        calls: [
+            { module: 'documents', name: 'count', protoName: 'count', method: 'CountDocuments', rpc: 'loams.collection.v1.DocumentService/CountDocuments', service: 'loams.collection.v1.DocumentService', package: 'loams.collection.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'documents', name: 'deleteByFilter', protoName: 'delete_by_filter', method: 'DeleteByFilter', rpc: 'loams.collection.v1.DocumentService/DeleteByFilter', service: 'loams.collection.v1.DocumentService', package: 'loams.collection.v1', idempotency: 'none', retry: 'manual', streaming: 'unary', pagination: null },
+            { module: 'documents', name: 'get', protoName: 'get', method: 'GetDocuments', rpc: 'loams.collection.v1.DocumentService/GetDocuments', service: 'loams.collection.v1.DocumentService', package: 'loams.collection.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'documents', name: 'patchByFilter', protoName: 'patch_by_filter', method: 'PatchByFilter', rpc: 'loams.collection.v1.DocumentService/PatchByFilter', service: 'loams.collection.v1.DocumentService', package: 'loams.collection.v1', idempotency: 'none', retry: 'manual', streaming: 'unary', pagination: null },
+            { module: 'documents', name: 'scroll', protoName: 'scroll', method: 'ScrollDocuments', rpc: 'loams.collection.v1.DocumentService/ScrollDocuments', service: 'loams.collection.v1.DocumentService', package: 'loams.collection.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'documents', name: 'write', protoName: 'write', method: 'WriteDocuments', rpc: 'loams.collection.v1.DocumentService/WriteDocuments', service: 'loams.collection.v1.DocumentService', package: 'loams.collection.v1', idempotency: 'none', retry: 'manual', streaming: 'unary', pagination: null },
+        ],
+    },
+    {
+        name: 'graph',
+        summary: 'Loams Graph: stored property graphs, queried with GQL.',
+        service: 'loams.graph.v1.GraphAdminService',
+        package: 'loams.graph.v1',
+        unstable: true,
+        derived: false,
+        calls: [
+            { module: 'graph', name: 'create', protoName: 'create', method: 'CreateGraph', rpc: 'loams.graph.v1.GraphAdminService/CreateGraph', service: 'loams.graph.v1.GraphAdminService', package: 'loams.graph.v1', idempotency: 'none', retry: 'manual', streaming: 'unary', pagination: null },
+            { module: 'graph', name: 'delete', protoName: 'delete', method: 'DeleteGraph', rpc: 'loams.graph.v1.GraphAdminService/DeleteGraph', service: 'loams.graph.v1.GraphAdminService', package: 'loams.graph.v1', idempotency: 'none', retry: 'manual', streaming: 'unary', pagination: null },
+            { module: 'graph', name: 'explain', protoName: 'explain', method: 'Explain', rpc: 'loams.graph.v1.GraphService/Explain', service: 'loams.graph.v1.GraphService', package: 'loams.graph.v1', idempotency: 'none', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'graph', name: 'get', protoName: 'get', method: 'GetGraph', rpc: 'loams.graph.v1.GraphAdminService/GetGraph', service: 'loams.graph.v1.GraphAdminService', package: 'loams.graph.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'graph', name: 'list', protoName: 'list', method: 'ListGraphs', rpc: 'loams.graph.v1.GraphAdminService/ListGraphs', service: 'loams.graph.v1.GraphAdminService', package: 'loams.graph.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: { items: 'graphs', nextPageToken: 'nextPageToken' } },
+            { module: 'graph', name: 'query', protoName: 'query', method: 'Execute', rpc: 'loams.graph.v1.GraphService/Execute', service: 'loams.graph.v1.GraphService', package: 'loams.graph.v1', idempotency: 'none', retry: 'manual', streaming: 'unary', pagination: null },
+            { module: 'graph', name: 'queryBatch', protoName: 'query_batch', method: 'ExecuteBatch', rpc: 'loams.graph.v1.GraphService/ExecuteBatch', service: 'loams.graph.v1.GraphService', package: 'loams.graph.v1', idempotency: 'none', retry: 'manual', streaming: 'unary', pagination: null },
+            { module: 'graph', name: 'queryStream', protoName: 'query_stream', method: 'ExecuteStream', rpc: 'loams.graph.v1.GraphService/ExecuteStream', service: 'loams.graph.v1.GraphService', package: 'loams.graph.v1', idempotency: 'none', retry: 'manual', streaming: 'server', pagination: null },
+            { module: 'graph', name: 'schema', protoName: 'schema', method: 'GetSchema', rpc: 'loams.graph.v1.GraphAdminService/GetSchema', service: 'loams.graph.v1.GraphAdminService', package: 'loams.graph.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'graph', name: 'update', protoName: 'update', method: 'UpdateGraph', rpc: 'loams.graph.v1.GraphAdminService/UpdateGraph', service: 'loams.graph.v1.GraphAdminService', package: 'loams.graph.v1', idempotency: 'none', retry: 'manual', streaming: 'unary', pagination: null },
+        ],
+    },
     {
         name: 'instance',
         summary: 'What this instance is, and who the caller is on it.',
@@ -166,6 +226,58 @@ export const MODULES = [
             { module: 'live.admin', name: 'updateApp', protoName: 'updateApp', method: 'UpdateApp', rpc: 'loams.live.v1.LiveAdminService/UpdateApp', service: 'loams.live.v1.LiveAdminService', package: 'loams.live.v1', idempotency: 'none', retry: 'manual', streaming: 'unary', pagination: null },
         ],
     },
+    {
+        name: 'namespaces',
+        summary: 'Namespaces: the container every collection and stream lives in.',
+        service: 'loams.collection.v1.NamespaceService',
+        package: 'loams.collection.v1',
+        unstable: false,
+        derived: false,
+        calls: [
+            { module: 'namespaces', name: 'create', protoName: 'create', method: 'CreateNamespace', rpc: 'loams.collection.v1.NamespaceService/CreateNamespace', service: 'loams.collection.v1.NamespaceService', package: 'loams.collection.v1', idempotency: 'none', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'namespaces', name: 'list', protoName: 'list', method: 'ListNamespaces', rpc: 'loams.collection.v1.NamespaceService/ListNamespaces', service: 'loams.collection.v1.NamespaceService', package: 'loams.collection.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: { items: 'namespaces', nextPageToken: 'nextPageToken' } },
+        ],
+    },
+    {
+        name: 'search',
+        summary: 'Queries: one search over one collection, dense, sparse, text or hybrid.',
+        service: 'loams.collection.v1.QueryService',
+        package: 'loams.collection.v1',
+        unstable: false,
+        derived: false,
+        calls: [
+            { module: 'search', name: 'query', protoName: 'query', method: 'Search', rpc: 'loams.collection.v1.QueryService/Search', service: 'loams.collection.v1.QueryService', package: 'loams.collection.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: null },
+        ],
+    },
+    {
+        name: 'sql',
+        summary: 'SQL: one read-only statement over a namespace\'s collections, with parameters.',
+        service: 'loams.sql.v1.SqlService',
+        package: 'loams.sql.v1',
+        unstable: false,
+        derived: false,
+        calls: [
+            { module: 'sql', name: 'query', protoName: 'query', method: 'Query', rpc: 'loams.sql.v1.SqlService/Query', service: 'loams.sql.v1.SqlService', package: 'loams.sql.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'sql', name: 'queryArrow', protoName: 'query_arrow', method: 'QueryArrow', rpc: 'loams.sql.v1.SqlService/QueryArrow', service: 'loams.sql.v1.SqlService', package: 'loams.sql.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: null },
+        ],
+    },
+    {
+        name: 'streams',
+        summary: 'Streams: create, list and describe a namespace\'s logs; produce and fetch records and CloudEvents.',
+        service: 'loams.stream.v1.StreamService',
+        package: 'loams.stream.v1',
+        unstable: false,
+        derived: false,
+        calls: [
+            { module: 'streams', name: 'create', protoName: 'create', method: 'CreateStream', rpc: 'loams.stream.v1.StreamService/CreateStream', service: 'loams.stream.v1.StreamService', package: 'loams.stream.v1', idempotency: 'none', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'streams', name: 'fetch', protoName: 'fetch', method: 'Fetch', rpc: 'loams.stream.v1.StreamService/Fetch', service: 'loams.stream.v1.StreamService', package: 'loams.stream.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'streams', name: 'fetchEvents', protoName: 'fetch_events', method: 'FetchCloudEvents', rpc: 'loams.stream.v1.StreamService/FetchCloudEvents', service: 'loams.stream.v1.StreamService', package: 'loams.stream.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'streams', name: 'get', protoName: 'get', method: 'DescribeStream', rpc: 'loams.stream.v1.StreamService/DescribeStream', service: 'loams.stream.v1.StreamService', package: 'loams.stream.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: null },
+            { module: 'streams', name: 'list', protoName: 'list', method: 'ListStreams', rpc: 'loams.stream.v1.StreamService/ListStreams', service: 'loams.stream.v1.StreamService', package: 'loams.stream.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: { items: 'streams', nextPageToken: 'nextPageToken' } },
+            { module: 'streams', name: 'produce', protoName: 'produce', method: 'Produce', rpc: 'loams.stream.v1.StreamService/Produce', service: 'loams.stream.v1.StreamService', package: 'loams.stream.v1', idempotency: 'none', retry: 'manual', streaming: 'unary', pagination: null },
+            { module: 'streams', name: 'produceEvents', protoName: 'produce_events', method: 'ProduceCloudEvents', rpc: 'loams.stream.v1.StreamService/ProduceCloudEvents', service: 'loams.stream.v1.StreamService', package: 'loams.stream.v1', idempotency: 'none', retry: 'manual', streaming: 'unary', pagination: null },
+        ],
+    },
     {
         name: 'tables',
         summary: '',
@@ -178,6 +290,17 @@ export const MODULES = [
             { module: 'tables', name: 'query', protoName: 'query', method: 'Query', rpc: 'loams.live.v1.LiveService/Query', service: 'loams.live.v1.LiveService', package: 'loams.live.v1', idempotency: 'none', retry: 'manual', streaming: 'unary', pagination: null },
         ],
     },
+    {
+        name: 'vector',
+        summary: '',
+        service: 'loams.collection.v1.QueryService',
+        package: 'loams.collection.v1',
+        unstable: false,
+        derived: true,
+        calls: [
+            { module: 'vector', name: 'search', protoName: 'search', method: 'Search', rpc: 'loams.collection.v1.QueryService/Search', service: 'loams.collection.v1.QueryService', package: 'loams.collection.v1', idempotency: 'no_side_effects', retry: 'safe', streaming: 'unary', pagination: null },
+        ],
+    },
 ];
 /**
 *  The generated service descriptors, by fully qualified name. The runtime
@@ -192,9 +315,17 @@ export const SERVICE_DESCRIPTORS = {
     'loams.admin.v1.OrgService': OrgService,
     'loams.admin.v1.ProjectService': ProjectService,
     'loams.auth.v1.AuthService': AuthService,
+    'loams.collection.v1.CollectionService': CollectionService,
+    'loams.collection.v1.DocumentService': DocumentService,
+    'loams.collection.v1.NamespaceService': NamespaceService,
+    'loams.collection.v1.QueryService': QueryService,
+    'loams.graph.v1.GraphAdminService': GraphAdminService,
+    'loams.graph.v1.GraphService': GraphService,
     'loams.instance.v1.InstanceService': InstanceService,
     'loams.live.v1.LiveAdminService': LiveAdminService,
     'loams.live.v1.LiveService': LiveService,
+    'loams.sql.v1.SqlService': SqlService,
+    'loams.stream.v1.StreamService': StreamService,
 };
 /** The proto packages this SDK speaks, as `GetInstance.api_versions` names them. */
 export const PROTO_PACKAGES = [
@@ -210,11 +341,14 @@ export const PROTO_PACKAGES = [
     'loams.instance.v1',
     'loams.live.v1',
     'loams.live.worker.v1',
+    'loams.memory.v1',
     'loams.notifications.v1',
     'loams.operations.v1',
     'loams.options.v1',
     'loams.postgres.v1',
     'loams.repos.v1',
+    'loams.sql.v1',
+    'loams.stream.v1',
 ];
 /**
 *  Every `reason` in `docs/api/reasons.md` (design §44 §7.4, D611). Within
@@ -271,6 +405,7 @@ export const REASONS = [
     'idempotency_key_reused',
     'workspace_not_found',
     'workspace_fenced',
+    'batch_partially_applied',
     'workspace_read_only',
     'workspace_name_taken',
     'object_missing',
@@ -278,17 +413,46 @@ export const REASONS = [
     'env_unsealed',
     'env_access_denied',
     'env_foreign_reference',
+    'memory_store_not_found',
+    'memory_space_not_found',
+    'memory_space_limit',
+    'memory_managed_object',
+    'memory_block_version_mismatch',
+    'memory_block_too_large',
+    'memory_core_budget_exceeded',
+    'memory_content_too_large',
+    'memory_secret_detected',
+    'memory_pii_refused',
+    'memory_model_not_configured',
+    'memory_model_not_local',
+    'memory_token_budget_exhausted',
+    'memory_extraction_failed',
+    'memory_too_many_spaces',
+    'memory_cross_space_write',
+    'memory_not_yet_available',
+    'code_repo_not_indexed',
+    'code_index_building',
+    'code_change_too_large',
+    'code_language_unsupported',
+    'code_scip_invalid',
     'live_bad_cursor',
     'live_worker_crashed',
     'live_deploy_conflict',
     'live_schema_violation',
+    'filter_conflict',
+    'search_after_needs_tiebreak',
+    'invalid_consistency_token',
+    'namespace_required',
+    'sql_param_count',
     'live_index_not_ready',
     'live_app_disabled',
     'live_app_exists',
     'live_function_error',
     'live_function_timeout',
+    'client_deadline_exceeded',
     'live_function_out_of_memory',
     'live_limit_exceeded',
+    'result_too_large',
     'live_app_mismatch',
     'live_origin_not_allowed',
     'session_rotate',
@@ -376,6 +540,7 @@ export const REASON_CODES = {
     idempotency_key_reused: 'failed_precondition',
     workspace_not_found: 'not_found',
     workspace_fenced: 'aborted',
+    batch_partially_applied: 'aborted',
     workspace_read_only: 'failed_precondition',
     workspace_name_taken: 'already_exists',
     object_missing: 'failed_precondition',
@@ -383,17 +548,46 @@ export const REASON_CODES = {
     env_unsealed: 'invalid_argument',
     env_access_denied: 'permission_denied',
     env_foreign_reference: 'permission_denied',
+    memory_store_not_found: 'not_found',
+    memory_space_not_found: 'not_found',
+    memory_space_limit: 'resource_exhausted',
+    memory_managed_object: 'failed_precondition',
+    memory_block_version_mismatch: 'aborted',
+    memory_block_too_large: 'invalid_argument',
+    memory_core_budget_exceeded: 'resource_exhausted',
+    memory_content_too_large: 'invalid_argument',
+    memory_secret_detected: 'failed_precondition',
+    memory_pii_refused: 'failed_precondition',
+    memory_model_not_configured: 'failed_precondition',
+    memory_model_not_local: 'failed_precondition',
+    memory_token_budget_exhausted: 'resource_exhausted',
+    memory_extraction_failed: 'failed_precondition',
+    memory_too_many_spaces: 'invalid_argument',
+    memory_cross_space_write: 'invalid_argument',
+    memory_not_yet_available: 'unimplemented',
+    code_repo_not_indexed: 'failed_precondition',
+    code_index_building: 'unavailable',
+    code_change_too_large: 'invalid_argument',
+    code_language_unsupported: 'failed_precondition',
+    code_scip_invalid: 'invalid_argument',
     live_bad_cursor: 'invalid_argument',
     live_worker_crashed: 'internal',
     live_deploy_conflict: 'failed_precondition',
     live_schema_violation: 'invalid_argument',
+    filter_conflict: 'invalid_argument',
+    search_after_needs_tiebreak: 'invalid_argument',
+    invalid_consistency_token: 'invalid_argument',
+    namespace_required: 'invalid_argument',
+    sql_param_count: 'invalid_argument',
     live_index_not_ready: 'failed_precondition',
     live_app_disabled: 'failed_precondition',
     live_app_exists: 'failed_precondition',
     live_function_error: 'unknown',
     live_function_timeout: 'deadline_exceeded',
+    client_deadline_exceeded: 'deadline_exceeded',
     live_function_out_of_memory: 'resource_exhausted',
     live_limit_exceeded: 'resource_exhausted',
+    result_too_large: 'resource_exhausted',
     live_app_mismatch: 'permission_denied',
     live_origin_not_allowed: 'permission_denied',
     session_rotate: 'unavailable',

package/dist/handle.d.ts

@@ -0,0 +1,67 @@
+import { type JsonObject } from '@bufbuild/protobuf';
+import type { DocumentInput, PatchChange, ScrollOptions, Target, UnaryCall } from './app.js';
+import type { DocId, FilterJson } from './builders/filter.js';
+import { Search, type VectorOptions } from './builders/search.js';
+import type { BatchOptions, BatchResult } from './runtime/batch.js';
+import type { CallOptions } from './runtime/call.js';
+/** The module calls a handle delegates to. Each is optional so a handle can
+ * be built over a facade that lacks a module; calling into a missing one is a
+ * clear error rather than a `TypeError`. */
+export interface HandleModules {
+    documents?: {
+        upsert?: (target: Target, docs: DocumentInput[], options?: CallOptions) => Promise<unknown>;
+        delete?: (target: Target, ids: DocId[], options?: CallOptions) => Promise<unknown>;
+        patch?: (target: Target, id: DocId, change: PatchChange, options?: CallOptions) => Promise<unknown>;
+        writeBatch?: (target: Target, docs: Iterable<DocumentInput> | AsyncIterable<DocumentInput>, options?: BatchOptions & CallOptions) => Promise<BatchResult>;
+        scrollAll?: (target: Target, options?: ScrollOptions) => AsyncGenerator<unknown>;
+        get?: UnaryCall;
+        count?: UnaryCall;
+    };
+    search?: {
+        query?: UnaryCall;
+    };
+    collections?: {
+        get?: UnaryCall;
+        drop?: UnaryCall;
+    };
+}
+/** A collection, by name, with the document and search calls bound to it. */
+export declare class CollectionHandle {
+    #private;
+    readonly name: string;
+    readonly namespace: string | undefined;
+    constructor(modules: HandleModules, name: string, options?: {
+        namespace?: string;
+    });
+    /** Writes (creates or replaces) documents. */
+    upsert(docs: DocumentInput[], options?: CallOptions): Promise<unknown>;
+    /** Reads documents by id. */
+    get(ids: DocId[], options?: CallOptions & {
+        select?: JsonObject;
+    }): Promise<any>;
+    /** Removes documents by id. */
+    delete(ids: DocId[], options?: CallOptions): Promise<unknown>;
+    /** Changes part of one document. */
+    patch(id: DocId, change: PatchChange, options?: CallOptions): Promise<unknown>;
+    /** A chunked bulk upsert (R13). */
+    writeBatch(docs: Iterable<DocumentInput> | AsyncIterable<DocumentInput>, options?: BatchOptions & CallOptions): Promise<BatchResult>;
+    /** How many documents match `where` (every document without one). */
+    count(options?: CallOptions & {
+        where?: FilterJson;
+    }): Promise<any>;
+    /** Every document, page by page. */
+    scrollAll(options?: ScrollOptions): AsyncGenerator<unknown, any, any>;
+    /** A search builder already pointed at this collection. */
+    query(): Search;
+    /** Runs a search; the builder's collection is replaced by this one. */
+    search(builder: Search, options?: CallOptions): Promise<any>;
+    /** A kNN search on one vector field. */
+    vectorSearch(field: string, vector: readonly number[], options?: CallOptions & VectorOptions & {
+        limit?: number;
+        filter?: FilterJson;
+    }): Promise<any>;
+    /** The collection's schema and stats. */
+    info(options?: CallOptions): Promise<any>;
+    /** Drops the collection. */
+    drop(options?: CallOptions): Promise<any>;
+}

package/dist/handle.js

@@ -0,0 +1,107 @@
+// The collection handle (SDKP §2.8).
+//
+//   const notes = loams.collection('notes');
+//   await notes.upsert([{ id: 1, source: { title: 'Refunds' } }]);
+//   const hits = await notes.search(notes.query().text('refund', { fields: ['body'] }));
+//
+// Every call delegates to the module call of the same meaning with
+// `collection` (and `namespace`, when the handle was given one) filled in. The
+// handle holds no state of its own: two handles on the same collection are
+// interchangeable, and a handle is as cheap as the object literal it is.
+import { fromJson } from '@bufbuild/protobuf';
+import { Code } from '@connectrpc/connect';
+import { DocumentIdSchema } from './vendor/proto/gen/loams/collection/v1/document_pb.js';
+import { Search } from './builders/search.js';
+import { LoamsError } from './runtime/errors.js';
+import { documentIdJson } from './app.js';
+function need(fn, name) {
+    if (fn === undefined) {
+        throw new LoamsError(`this SDK's facade has no ${name}`, { code: Code.Unimplemented });
+    }
+    return fn;
+}
+/** A collection, by name, with the document and search calls bound to it. */
+export class CollectionHandle {
+    name;
+    namespace;
+    #modules;
+    constructor(modules, name, options = {}) {
+        this.#modules = modules;
+        this.name = name;
+        this.namespace = options.namespace;
+    }
+    get #target() {
+        return this.namespace === undefined
+            ? { collection: this.name }
+            : { collection: this.name, namespace: this.namespace };
+    }
+    /** The request fields every call carries. */
+    get #fields() {
+        return this.#target;
+    }
+    /** Writes (creates or replaces) documents. */
+    upsert(docs, options) {
+        return need(this.#modules.documents?.upsert, 'documents.upsert')(this.#target, docs, options);
+    }
+    /** Reads documents by id. */
+    get(ids, options = {}) {
+        const { select, ...call } = options;
+        return need(this.#modules.documents?.get, 'documents.get')({
+            ...this.#fields,
+            ids: ids.map((id) => fromJson(DocumentIdSchema, documentIdJson(id))),
+            ...(select === undefined ? {} : { select }),
+        }, call);
+    }
+    /** Removes documents by id. */
+    delete(ids, options) {
+        return need(this.#modules.documents?.delete, 'documents.delete')(this.#target, ids, options);
+    }
+    /** Changes part of one document. */
+    patch(id, change, options) {
+        return need(this.#modules.documents?.patch, 'documents.patch')(this.#target, id, change, options);
+    }
+    /** A chunked bulk upsert (R13). */
+    writeBatch(docs, options) {
+        return need(this.#modules.documents?.writeBatch, 'documents.writeBatch')(this.#target, docs, options);
+    }
+    /** How many documents match `where` (every document without one). */
+    count(options = {}) {
+        const { where, ...call } = options;
+        return need(this.#modules.documents?.count, 'documents.count')({ ...this.#fields, ...(where === undefined ? {} : { where }) }, call);
+    }
+    /** Every document, page by page. */
+    scrollAll(options) {
+        return need(this.#modules.documents?.scrollAll, 'documents.scrollAll')(this.#target, options);
+    }
+    /** A search builder already pointed at this collection. */
+    query() {
+        return Search.on(this.name, this.namespace === undefined ? {} : { namespace: this.namespace });
+    }
+    /** Runs a search; the builder's collection is replaced by this one. */
+    search(builder, options) {
+        const json = builder.toJson();
+        json.collection = this.name;
+        if (this.namespace !== undefined) {
+            json.namespace = this.namespace;
+        }
+        return need(this.#modules.search?.query, 'search.query')(Search.fromJson(json).build(), options);
+    }
+    /** A kNN search on one vector field. */
+    vectorSearch(field, vector, options = {}) {
+        const { limit, filter, k, exact, nprobes, refineFactor, ef, oversampling, distance, ...call } = options;
+        let builder = this.query().vector(field, vector, { k, exact, nprobes, refineFactor, ef, oversampling, distance });
+        if (filter !== undefined)
+            builder = builder.filter(filter);
+        if (limit !== undefined)
+            builder = builder.limit(limit);
+        return this.search(builder, call);
+    }
+    /** The collection's schema and stats. */
+    info(options) {
+        return need(this.#modules.collections?.get, 'collections.get')(this.#fields, options);
+    }
+    /** Drops the collection. */
+    drop(options) {
+        return need(this.#modules.collections?.drop, 'collections.drop')(this.#fields, options);
+    }
+}

package/dist/index.d.ts

@@ -1,9 +1,16 @@
-export { Loams, type AdminNamespace, type LiveNamespace, type LoamsModules, type LoamsOptions, } from './loams.js';
+export { Loams, type AdminNamespace, type CollectionsNamespace, type DocumentsNamespace, type LiveNamespace, type NamespacesNamespace, type SearchNamespace, type SqlNamespace, type StreamsNamespace, type LoamsEnvironment, type LoamsModules, type LoamsOptions, } from './loams.js';
+export { Schema, type DynamicMapping, type FieldOptions, type TextOptions as SchemaTextOptions } from './builders/schema.js';
+export { Filter, idValue, toQuery, type Bounds, type DocId, type FilterJson, type Fuzziness, type MatchOptions, type MultiMatchOptions, type QueryStringOptions, } from './builders/filter.js';
+export { Fusion, Search, Sort, consistencyJson, dbsf, rrf, weighted, type ConsistencyLevel, type ExpandOptions, type FusionJson, type HighlightOptions, type SelectOptions, type SortJson, type SortValue, type SparseOptions, type TextOptions, type VectorOptions, } from './builders/search.js';
+export { CollectionHandle, type HandleModules } from './handle.js';
+export { WriteOps, attachAppCalls, documentCalls, documentIdJson, searchCalls, sqlCalls, sqlRecords, streamCalls, type DocumentInput, type PatchChange, type ScrollOptions, type SearchShorthandOptions, type SqlAnswer, type SqlRecordsOptions, type Target, } from './app.js';
+export { DEFAULT_CHUNK_BYTES, DEFAULT_CHUNK_ROWS, writeBatch, type BatchOptions, type BatchResult, type ChunkWriter, } from './runtime/batch.js';
+export { SUBSCRIBE_MAX_BACKOFF_MS, SUBSCRIBE_MIN_BACKOFF_MS, subscribe, type OffsetRecord, type RecordFetcher, type SubscribeRequest, type Subscription, } from './runtime/subscribe.js';
 export { SystemApi, type Catalogue, type SystemConfig, type VersionReport, } from './system.js';
-export { FEATURE_NOT_IN_VARIANT, MODULES, PROTO_PACKAGES, PROTO_REV, REASON_CODES, REASONS, SERVICE_DESCRIPTORS, type CallBinding, type InstanceModule, type LiveModule, type ModuleBinding, type Reason, type TablesModule, } from './gen/facade.js';
-export { CallInvoker, callWithRetry, withIdempotencyKey, type Attempt, type CallOptions, type ConsistencyOptions, type ConsistencyTokenStore, type RetryPlan, type Send, } from './runtime/call.js';
-export { ConsistencySession, TOKEN_PREFIX, isConsistencyToken } from './runtime/consistency.js';
-export { AlreadyExistsError, AbortedError, DeadlineExceededError, FailedPreconditionError, FeatureNotInVariantError, InternalError, InvalidArgumentError, LoamsError, NotFoundError, PermissionDeniedError, ResourceExhaustedError, TokenExpiredError, UnauthenticatedError, UnavailableError, UnimplementedError, errorInfo, isLoamsError, toLoamsError, type ErrorInfoShape, } from './runtime/errors.js';
+export { FEATURE_NOT_IN_VARIANT, MODULES, PROTO_PACKAGES, PROTO_REV, REASON_CODES, REASONS, SERVICE_DESCRIPTORS, type CallBinding, type CollectionsModule, type DocumentsModule, type GraphModule, type InstanceModule, type NamespacesModule, type SearchModule, type VectorModule, type LiveModule, type ModuleBinding, type Reason, type TablesModule, } from './gen/facade.js';
+export { CONSISTENCY_TOKEN_HEADER, CallInvoker, DEFAULT_TIMEOUT_MS, callWithRetry, withIdempotencyKey, type Attempt, type CallOptions, type ConsistencyOptions, type ConsistencyTokenStore, type InvokerDefaults, type RetryPlan, type Send, } from './runtime/call.js';
+export { ConsistencySession, ConsistencyToken, TOKEN_PREFIX, isConsistencyToken, type TokenPosition, } from './runtime/consistency.js';
+export { AlreadyExistsError, AbortedError, BatchError, CLIENT_REASONS, DeadlineExceededError, FailedPreconditionError, FeatureNotInVariantError, InternalError, InvalidArgumentError, LoamsError, NotFoundError, PermissionDeniedError, ResourceExhaustedError, TokenExpiredError, UnauthenticatedError, UnavailableError, UnimplementedError, errorInfo, isLoamsError, type ClientReason, toLoamsError, type ErrorInfoShape, } from './runtime/errors.js';
 export { paginate, pageFields, type PageFetcher, type PageRequestOptions } from './runtime/pagination.js';
 export { BASE_DELAY_MS, DEFAULT_MAX_RETRIES, MAX_DELAY_MS, MAX_SERVER_DELAY_MS, backoffMs, isRetryableCode, shouldRetry, sleep, } from './runtime/retry.js';
 export { watch, type CursorOf, type ResumeOptions, type StreamOpener } from './runtime/streams.js';

package/dist/index.js

@@ -15,15 +15,24 @@
 // generator produced, the typed error hierarchy, the token sources, and the
 // reason registry as a type.
 export { Loams, } from './loams.js';
+// The app-building layer (SDKP): the builders, the collection handle and the
+// hand-written conveniences the module objects carry.
+export { Schema } from './builders/schema.js';
+export { Filter, idValue, toQuery, } from './builders/filter.js';
+export { Fusion, Search, Sort, consistencyJson, dbsf, rrf, weighted, } from './builders/search.js';
+export { CollectionHandle } from './handle.js';
+export { WriteOps, attachAppCalls, documentCalls, documentIdJson, searchCalls, sqlCalls, sqlRecords, streamCalls, } from './app.js';
+export { DEFAULT_CHUNK_BYTES, DEFAULT_CHUNK_ROWS, writeBatch, } from './runtime/batch.js';
+export { SUBSCRIBE_MAX_BACKOFF_MS, SUBSCRIBE_MIN_BACKOFF_MS, subscribe, } from './runtime/subscribe.js';
 export { SystemApi, } from './system.js';
 // The generated facade: the module interfaces, the binding table, the proto
 // revision, and the reason registry as a type. Everything here is written by
 // `buf generate`; do not hand-edit it.
 export { FEATURE_NOT_IN_VARIANT, MODULES, PROTO_PACKAGES, PROTO_REV, REASON_CODES, REASONS, SERVICE_DESCRIPTORS, } from './gen/facade.js';
 // The runtime, for a caller who composes rather than uses.
-export { CallInvoker, callWithRetry, withIdempotencyKey, } from './runtime/call.js';
-export { ConsistencySession, TOKEN_PREFIX, isConsistencyToken } from './runtime/consistency.js';
-export { AlreadyExistsError, AbortedError, DeadlineExceededError, FailedPreconditionError, FeatureNotInVariantError, InternalError, InvalidArgumentError, LoamsError, NotFoundError, PermissionDeniedError, ResourceExhaustedError, TokenExpiredError, UnauthenticatedError, UnavailableError, UnimplementedError, errorInfo, isLoamsError, toLoamsError, } from './runtime/errors.js';
+export { CONSISTENCY_TOKEN_HEADER, CallInvoker, DEFAULT_TIMEOUT_MS, callWithRetry, withIdempotencyKey, } from './runtime/call.js';
+export { ConsistencySession, ConsistencyToken, TOKEN_PREFIX, isConsistencyToken, } from './runtime/consistency.js';
+export { AlreadyExistsError, AbortedError, BatchError, CLIENT_REASONS, DeadlineExceededError, FailedPreconditionError, FeatureNotInVariantError, InternalError, InvalidArgumentError, LoamsError, NotFoundError, PermissionDeniedError, ResourceExhaustedError, TokenExpiredError, UnauthenticatedError, UnavailableError, UnimplementedError, errorInfo, isLoamsError, toLoamsError, } from './runtime/errors.js';
 export { paginate, pageFields } from './runtime/pagination.js';
 export { BASE_DELAY_MS, DEFAULT_MAX_RETRIES, MAX_DELAY_MS, MAX_SERVER_DELAY_MS, backoffMs, isRetryableCode, shouldRetry, sleep, } from './runtime/retry.js';
 export { watch } from './runtime/streams.js';