dataceen-client 0.0.1

package/dist/runtime/aggregations.js

@@ -0,0 +1,24 @@
+/**
+ * Aggregation types — matches the C# client's Aggregation/Bucket classes
+ * and the Dataceen server's aggregation output shape.
+ *
+ * The server's introspection does not advertise the Aggregations field on
+ * <Entity>SearchResult, but it returns them when the query asks for them.
+ * We expand the fragment at a fixed depth (aggregationFragment) so callers
+ * can nest up to N levels without writing raw GraphQL.
+ */
+/**
+ * Builds a GraphQL selection fragment for the Aggregations field at a given
+ * nesting depth. Deeper than the supplied depth, nested aggregations are
+ * returned by the server but silently dropped by the selection.
+ */
+export function aggregationFragment(depth) {
+    const scalarFields = "Name SumOtherDocCount DocCountErrorUpperBound Value";
+    let fragment = `Aggregations { ${scalarFields} Buckets { Key Count } }`;
+    for (let i = 0; i < depth - 1; i++) {
+        fragment = `Aggregations { ${scalarFields} Buckets { Key Count ${fragment} } }`;
+    }
+    return fragment;
+}
+/** Default depth used by doSearch when the caller does not specify one. */
+export const DEFAULT_AGGREGATION_DEPTH = 3;

package/dist/runtime/fields.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Field-selection proxy runtime. Used by generated `<Entity>Fields`-types.
+ *
+ * Stabilized version of `src/prototypes/b-proxy/build.ts`'s makeFieldsProxy,
+ * adapted to emit a GraphQL fragment string directly (instead of the AST
+ * used by prototype comparison tests).
+ *
+ * Usage (in generated client code):
+ *   const fragment = collectFields<Customer>(f => {
+ *     f._id;
+ *     f.CustomerId;
+ *     f.CustomerPlacedOrder(r => r.Order(o => o.OrderId));
+ *   });
+ *   // → "_id CustomerId CustomerPlacedOrder { Order { OrderId } }"
+ */
+/**
+ * Proxy type exposed to the user's fields lambda. Scalars are property-access
+ * chainable; nested objects/arrays are callable with an inner lambda.
+ *
+ * `-?` strips optional modifiers so `f.NestedRelation(...)` isn't typed as
+ * possibly-undefined.
+ */
+export type FieldsProxy<T> = {
+    [K in keyof T]-?: NonNullable<T[K]> extends Array<infer U> ? (inner: (r: FieldsProxy<NonNullable<U>>) => void) => FieldsProxy<T> : NonNullable<T[K]> extends object ? (inner: (r: FieldsProxy<NonNullable<T[K]>>) => void) => FieldsProxy<T> : FieldsProxy<T>;
+};
+export declare function collectFields<T>(fn: (f: FieldsProxy<T>) => void): string;

package/dist/runtime/fields.js

@@ -0,0 +1,58 @@
+/**
+ * Field-selection proxy runtime. Used by generated `<Entity>Fields`-types.
+ *
+ * Stabilized version of `src/prototypes/b-proxy/build.ts`'s makeFieldsProxy,
+ * adapted to emit a GraphQL fragment string directly (instead of the AST
+ * used by prototype comparison tests).
+ *
+ * Usage (in generated client code):
+ *   const fragment = collectFields<Customer>(f => {
+ *     f._id;
+ *     f.CustomerId;
+ *     f.CustomerPlacedOrder(r => r.Order(o => o.OrderId));
+ *   });
+ *   // → "_id CustomerId CustomerPlacedOrder { Order { OrderId } }"
+ */
+export function collectFields(fn) {
+    const nodes = [];
+    fn(makeProxy(nodes));
+    return renderFragment(nodes);
+}
+function makeProxy(collector) {
+    const target = () => { };
+    const rootProxy = new Proxy(target, {
+        get(_t, prop) {
+            if (typeof prop === "symbol")
+                return undefined;
+            const name = String(prop);
+            if (name === "then")
+                return undefined; // avoid Promise-unwrap surprises
+            const idx = collector.length;
+            collector.push({ name, children: null }); // start as scalar
+            const continuation = function (inner) {
+                if (typeof inner === "function") {
+                    const children = [];
+                    inner(makeProxy(children));
+                    collector[idx] = { name, children };
+                }
+                return rootProxy;
+            };
+            return new Proxy(continuation, {
+                get(_tt, nextProp) {
+                    if (typeof nextProp === "symbol")
+                        return undefined;
+                    const n = String(nextProp);
+                    if (n === "then")
+                        return undefined;
+                    return rootProxy[n];
+                },
+            });
+        },
+    });
+    return rootProxy;
+}
+function renderFragment(nodes) {
+    return nodes
+        .map((n) => (n.children == null ? n.name : `${n.name} { ${renderFragment(n.children)} }`))
+        .join(" ");
+}

package/dist/runtime/filter.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Comparison operators — mirror the server's `*ComparisonExp` input types.
+ * All operator names are lowercase to match the wire format.
+ */
+export interface StringOps {
+    eq?: string;
+    neq?: string;
+    gt?: string;
+    gte?: string;
+    lt?: string;
+    lte?: string;
+    /**
+     * Token-based containment via Elasticsearch's `match` semantics.
+     * DO NOT use SQL-style wildcards (`%`, `*`) — they are treated literally.
+     * DO NOT include token delimiters (`-`, space, `.`) in the query — the server
+     * splits on them and OR-matches the parts, which usually isn't what you want.
+     * Correct usage: `{ CustomerId: { like: "cst" } }` matches all `cst-*` ids.
+     */
+    like?: string;
+    /** Inverse of `like`. Same token rules apply. */
+    nlike?: string;
+    /** Substring containment (not token-based). Use for exact substring matches. */
+    contains?: string;
+    /** Inverse of `contains`. */
+    ncontains?: string;
+    in?: string[];
+    nin?: string[];
+    is_null?: boolean;
+    exists?: boolean;
+}
+export interface NumberOps {
+    eq?: number;
+    neq?: number;
+    gt?: number;
+    gte?: number;
+    lt?: number;
+    lte?: number;
+    contains?: number;
+    ncontains?: number;
+    in?: number[];
+    nin?: number[];
+    is_null?: boolean;
+    exists?: boolean;
+}
+export interface BooleanOps {
+    eq?: boolean;
+    neq?: boolean;
+    is_null?: boolean;
+    exists?: boolean;
+}
+export interface DateOps {
+    eq?: string;
+    neq?: string;
+    gt?: string;
+    gte?: string;
+    lt?: string;
+    lte?: string;
+    contains?: string;
+    ncontains?: string;
+    in?: string[];
+    nin?: string[];
+    is_null?: boolean;
+    exists?: boolean;
+}
+/**
+ * Maps a scalar TS type to the right comparison-operator shape.
+ * Extend as new scalar kinds appear (e.g. Long → string via Decimal mapping).
+ */
+export type FilterOp<T> = T extends string ? StringOps : T extends number ? NumberOps : T extends boolean ? BooleanOps : never;
+/**
+ * Serializes a filter object to GraphQL-input syntax.
+ * Input is the user's filter literal; output is a string suitable for
+ * direct inclusion in a GraphQL query after `where:`.
+ *
+ *   filterToGraphQL({ CustomerId: { like: "cst-%" } })
+ *     → `{CustomerId: {like: "cst-%"}}`
+ */
+export declare function filterToGraphQL(value: unknown): string;

package/dist/runtime/filter.js

@@ -0,0 +1,30 @@
+/**
+ * Comparison operators — mirror the server's `*ComparisonExp` input types.
+ * All operator names are lowercase to match the wire format.
+ */
+/**
+ * Serializes a filter object to GraphQL-input syntax.
+ * Input is the user's filter literal; output is a string suitable for
+ * direct inclusion in a GraphQL query after `where:`.
+ *
+ *   filterToGraphQL({ CustomerId: { like: "cst-%" } })
+ *     → `{CustomerId: {like: "cst-%"}}`
+ */
+export function filterToGraphQL(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "null";
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value)) {
+        return `[${value.map(filterToGraphQL).join(", ")}]`;
+    }
+    if (typeof value === "object") {
+        const entries = Object.entries(value).filter(([, v]) => v !== undefined);
+        return `{${entries.map(([k, v]) => `${k}: ${filterToGraphQL(v)}`).join(", ")}}`;
+    }
+    return "null";
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,5 @@
+export { type StringOps, type NumberOps, type BooleanOps, type DateOps, type FilterOp, filterToGraphQL, } from "./filter.js";
+export { type FieldsProxy, collectFields, } from "./fields.js";
+export { type OrderByDirection, type OrderByEntry, orderByToGraphQL, } from "./order-by.js";
+export { type FindParams, type SearchParams, type RelationRef, doFind, doSearch, doCreate, doCreateBulk, doUpdate, doUpdateBulk, doDelete, doCreateRelation, doCreateRelationBulk, } from "./operations.js";
+export { type AggregationType, type AggregationDetails, type Bucket, type Aggregation, aggregationFragment, DEFAULT_AGGREGATION_DEPTH, } from "./aggregations.js";

package/dist/runtime/index.js

@@ -0,0 +1,5 @@
+export { filterToGraphQL, } from "./filter.js";
+export { collectFields, } from "./fields.js";
+export { orderByToGraphQL, } from "./order-by.js";
+export { doFind, doSearch, doCreate, doCreateBulk, doUpdate, doUpdateBulk, doDelete, doCreateRelation, doCreateRelationBulk, } from "./operations.js";
+export { aggregationFragment, DEFAULT_AGGREGATION_DEPTH, } from "./aggregations.js";

package/dist/runtime/operations.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Runtime helpers for generated <Entity>Client classes.
+ * Each helper builds a GraphQL query/mutation string from typed params and
+ * delegates to DataceenClient.executeQuery/executeMutation.
+ *
+ * Generated clients are thin wrappers — all query assembly lives here.
+ */
+import type { DataceenClient } from "../client/dataceen-client.js";
+import type { FindResult, MutationResult, SearchResult } from "../client/types.js";
+import { type OrderByEntry } from "./order-by.js";
+export interface FindParams<TRead, TFilter, TFields> {
+    size?: number;
+    cursor?: string;
+    filter?: TFilter;
+    fields?: (f: TFields) => void;
+    orderBy?: OrderByEntry<TRead>[];
+}
+export interface SearchParams<TRead, TSearchFilter, TFields, TAgg = unknown> extends FindParams<TRead, TSearchFilter, TFields> {
+    resultLookup?: "Full" | "WithinIndex";
+    /**
+     * Aggregation requests. Each element is a `Search<Entity>_aggregation` —
+     * a map with one entry per aggregated field. For multiple aggregations on
+     * different fields, pass multiple array entries.
+     */
+    aggregations?: TAgg[];
+    /**
+     * Nesting depth to request in the Aggregations result fragment.
+     * Defaults to 3 which suffices for typical multi-level aggregations.
+     */
+    aggregationDepth?: number;
+}
+export declare function doFind<TRead, TFilter, TFields>(client: DataceenClient, entity: string, params: FindParams<TRead, TFilter, TFields>): Promise<FindResult<TRead>>;
+export declare function doSearch<TRead, TSearchFilter, TFields, TAgg = unknown>(client: DataceenClient, entity: string, params: SearchParams<TRead, TSearchFilter, TFields, TAgg>): Promise<SearchResult<TRead>>;
+/** Create a single entity. Returns `MutationResult` with `Result: [newId]`. */
+export declare function doCreate<TCreate>(client: DataceenClient, entity: string, input: TCreate): Promise<MutationResult>;
+export declare function doCreateBulk<TCreate>(client: DataceenClient, entity: string, inputs: TCreate[]): Promise<MutationResult>;
+/**
+ * Update all entities matching `filter` with the non-undefined fields of `input`.
+ * `input` can be either:
+ *   - A plain partial object: { CustomerId: "new-id" }
+ *   - A generated *Update class: new CustomerUpdate(foundCustomer).CustomerId = "new-id"
+ * In the second case we call .toGraphQLInput() so only explicitly changed
+ * fields are sent (matches C# client semantics).
+ */
+export declare function doUpdate<TFilter, TUpdate>(client: DataceenClient, entity: string, filter: TFilter, input: TUpdate | ChangeTracked<TUpdate>): Promise<MutationResult>;
+export declare function doUpdateBulk<TUpdate>(client: DataceenClient, entity: string, inputs: (TUpdate | ChangeTracked<TUpdate>)[]): Promise<MutationResult>;
+export declare function doDelete<TFilter>(client: DataceenClient, entity: string, filter: TFilter): Promise<MutationResult>;
+export interface RelationRef {
+    from: string;
+    to: string;
+    /** The relationship type name, e.g. "CustomerPlacedOrder". */
+    relation: string;
+}
+export declare function doCreateRelation<TRelationCreate>(client: DataceenClient, ref: RelationRef, input: TRelationCreate): Promise<MutationResult>;
+export declare function doCreateRelationBulk<TRelationCreate>(client: DataceenClient, ref: RelationRef, inputs: TRelationCreate[]): Promise<MutationResult>;
+interface ChangeTracked<T> {
+    toGraphQLInput(): Partial<T>;
+}
+export {};

package/dist/runtime/operations.js

@@ -0,0 +1,112 @@
+import { collectFields } from "./fields.js";
+import { filterToGraphQL } from "./filter.js";
+import { orderByToGraphQL } from "./order-by.js";
+import { aggregationFragment, DEFAULT_AGGREGATION_DEPTH } from "./aggregations.js";
+/** Minimal default selection when the caller does not specify `fields`. */
+const MINIMAL_FIELDS = (f) => {
+    // @ts-expect-error _id exists on every generated entity's read-type
+    f._id;
+};
+export async function doFind(client, entity, params) {
+    const size = params.size ?? 50;
+    const cursor = params.cursor ?? "null";
+    const where = params.filter !== undefined ? filterToGraphQL(params.filter) : "null";
+    const fragment = collectFields(params.fields ?? MINIMAL_FIELDS);
+    const orderByArg = params.orderBy
+        ? `, order_by: ${orderByToGraphQL(params.orderBy)}`
+        : "";
+    const query = `query {Find${entity}(size: ${size}, cursor: "${cursor}", where: ${where}${orderByArg}) { Items { ${fragment} } Cursor ResponseTime }}`;
+    return client.executeQuery({
+        operationName: `Find${entity}`,
+        query,
+    });
+}
+export async function doSearch(client, entity, params) {
+    const size = params.size ?? 50;
+    const cursor = params.cursor ?? "null";
+    const resultLookup = params.resultLookup ?? "Full";
+    const where = params.filter !== undefined ? filterToGraphQL(params.filter) : "null";
+    const fragment = collectFields(params.fields ?? MINIMAL_FIELDS);
+    const orderByArg = params.orderBy
+        ? `, order_by: ${orderByToGraphQL(params.orderBy)}`
+        : "";
+    const hasAggs = params.aggregations && params.aggregations.length > 0;
+    const aggsArg = hasAggs ? `, aggregations: ${filterToGraphQL(params.aggregations)}` : "";
+    const aggsFragment = hasAggs
+        ? ` ${aggregationFragment(params.aggregationDepth ?? DEFAULT_AGGREGATION_DEPTH)}`
+        : "";
+    const query = `query {Search${entity}(size: ${size}, resultlookup: ${resultLookup}, cursor: "${cursor}", where: ${where}${orderByArg}${aggsArg}) { Items { ${fragment} } Cursor ResponseTime${aggsFragment} }}`;
+    return client.executeQuery({
+        operationName: `Search${entity}`,
+        query,
+    });
+}
+/** Create a single entity. Returns `MutationResult` with `Result: [newId]`. */
+export async function doCreate(client, entity, input) {
+    const query = `mutation {Create${entity}(${entity}: ${filterToGraphQL(input)}) { Result ResponseTime }}`;
+    return client.executeMutation({
+        operationName: `Create${entity}`,
+        query,
+    });
+}
+export async function doCreateBulk(client, entity, inputs) {
+    const query = `mutation {Create${entity}Bulk(${entity}List: ${filterToGraphQL(inputs)}) { Result ResponseTime }}`;
+    return client.executeMutation({
+        operationName: `Create${entity}Bulk`,
+        query,
+    });
+}
+/**
+ * Update all entities matching `filter` with the non-undefined fields of `input`.
+ * `input` can be either:
+ *   - A plain partial object: { CustomerId: "new-id" }
+ *   - A generated *Update class: new CustomerUpdate(foundCustomer).CustomerId = "new-id"
+ * In the second case we call .toGraphQLInput() so only explicitly changed
+ * fields are sent (matches C# client semantics).
+ */
+export async function doUpdate(client, entity, filter, input) {
+    const payload = isChangeTracked(input) ? input.toGraphQLInput() : input;
+    const query = `mutation {Update${entity}(where: ${filterToGraphQL(filter)}, ${entity}: ${filterToGraphQL(payload)}) { Result ResponseTime }}`;
+    return client.executeMutation({
+        operationName: `Update${entity}`,
+        query,
+    });
+}
+export async function doUpdateBulk(client, entity, inputs) {
+    const payloads = inputs.map((i) => (isChangeTracked(i) ? i.toGraphQLInput() : i));
+    const query = `mutation {Update${entity}Bulk(${entity}List: ${filterToGraphQL(payloads)}) { Result ResponseTime }}`;
+    return client.executeMutation({
+        operationName: `Update${entity}Bulk`,
+        query,
+    });
+}
+export async function doDelete(client, entity, filter) {
+    const query = `mutation {Delete${entity}(where: ${filterToGraphQL(filter)}) { Result ResponseTime }}`;
+    return client.executeMutation({
+        operationName: `Delete${entity}`,
+        query,
+    });
+}
+export async function doCreateRelation(client, ref, input) {
+    const mutationName = `Create${ref.from}${ref.relation}${ref.to}`;
+    const query = `mutation {${mutationName}(${ref.relation}: ${filterToGraphQL(input)}) { Result ResponseTime }}`;
+    return client.executeMutation({
+        operationName: mutationName,
+        query,
+    });
+}
+export async function doCreateRelationBulk(client, ref, inputs) {
+    const mutationName = `Create${ref.from}${ref.relation}${ref.to}Bulk`;
+    const argName = `${ref.relation}List`;
+    const query = `mutation {${mutationName}(${argName}: ${filterToGraphQL(inputs)}) { Result ResponseTime }}`;
+    return client.executeMutation({
+        operationName: mutationName,
+        query,
+    });
+}
+function isChangeTracked(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "toGraphQLInput" in value &&
+        typeof value.toGraphQLInput === "function");
+}

package/dist/runtime/order-by.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Order-by runtime. Serializes a user's order-by literal to GraphQL.
+ *
+ *   orderByToGraphQL([{ CustomerId: "Ascending" }, { ExternalReference: "Descending" }])
+ *     → `[{CustomerId: Ascending}, {ExternalReference: Descending}]`
+ *
+ * Nested-subgroup paths are preserved — the wire format requires the full
+ * path through the subgroup, not just the leaf:
+ *
+ *   orderByToGraphQL([{ Audit: { CreatedAt: "Descending" } }])
+ *     → `[{Audit: {CreatedAt: Descending}}]`
+ *
+ * Direction values are unquoted in the output — they are GraphQL enum values,
+ * not strings.
+ */
+export type OrderByDirection = "Ascending" | "Descending";
+/**
+ * A single sort clause. Each top-level key picks a field on `T`; the value is
+ * either a direction (for leaf scalars) or a nested entry (for subgroup
+ * objects like `Audit`, `Address`, `Profile`, …).
+ */
+export type OrderByEntry<T> = {
+    [K in keyof T]?: NonNullable<T[K]> extends object ? NonNullable<T[K]> extends Date | ReadonlyArray<unknown> ? OrderByDirection : OrderByEntry<NonNullable<T[K]>> : OrderByDirection;
+};
+export declare function orderByToGraphQL(entries: ReadonlyArray<Record<string, unknown>>): string;

package/dist/runtime/order-by.js

@@ -0,0 +1,49 @@
+/**
+ * Order-by runtime. Serializes a user's order-by literal to GraphQL.
+ *
+ *   orderByToGraphQL([{ CustomerId: "Ascending" }, { ExternalReference: "Descending" }])
+ *     → `[{CustomerId: Ascending}, {ExternalReference: Descending}]`
+ *
+ * Nested-subgroup paths are preserved — the wire format requires the full
+ * path through the subgroup, not just the leaf:
+ *
+ *   orderByToGraphQL([{ Audit: { CreatedAt: "Descending" } }])
+ *     → `[{Audit: {CreatedAt: Descending}}]`
+ *
+ * Direction values are unquoted in the output — they are GraphQL enum values,
+ * not strings.
+ */
+export function orderByToGraphQL(entries) {
+    const parts = [];
+    for (const entry of entries) {
+        for (const [field, value] of Object.entries(entry)) {
+            if (value === undefined || value === null)
+                continue;
+            if (typeof value === "object") {
+                const inner = serializeNested(value);
+                if (inner !== "")
+                    parts.push(`{${field}: {${inner}}}`);
+            }
+            else {
+                parts.push(`{${field}: ${value}}`);
+            }
+        }
+    }
+    return `[${parts.join(", ")}]`;
+}
+function serializeNested(obj) {
+    const parts = [];
+    for (const [field, value] of Object.entries(obj)) {
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value === "object") {
+            const inner = serializeNested(value);
+            if (inner !== "")
+                parts.push(`${field}: {${inner}}`);
+        }
+        else {
+            parts.push(`${field}: ${value}`);
+        }
+    }
+    return parts.join(", ");
+}

package/dist/subscriptions/grpc-client.d.ts

@@ -0,0 +1,36 @@
+import * as grpc from "@grpc/grpc-js";
+import type { SubscriptionRequest } from "./types.js";
+/** Raw event shape as delivered by the proto loader with `keepCase: true`. */
+export interface RawEventData {
+    messagetype: string;
+    eventtype: string;
+    position: string;
+    eventtime?: {
+        seconds: string;
+        nanos: number;
+    } | string;
+    objecttype: string;
+    operationtype: string;
+    clientid: string;
+    domain: string;
+    model: string;
+    topic: string;
+    id: string;
+    fromid: string;
+    toid: string;
+    delta: string;
+    complete: string;
+    positionbeforebaseload: string;
+}
+/**
+ * gRPC host/port from a SubscriptionUrl config value like "https://subscription.dataceen.com".
+ * grpc-js wants `host:port`, not URL, so we strip scheme and default the port.
+ */
+export declare function subscriptionHost(subscriptionUrl: string): string;
+export interface StreamSubscriberOptions {
+    subscriptionUrl: string;
+    accessToken: string;
+    request: SubscriptionRequest;
+}
+/** Open a gRPC stream. Returns a stream object + a close() function. */
+export declare function openSubscriptionStream(opts: StreamSubscriberOptions): grpc.ClientReadableStream<RawEventData>;

package/dist/subscriptions/grpc-client.js

@@ -0,0 +1,57 @@
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/** Path to the bundled dataceenevent.proto, relative to this module's location. */
+const PROTO_PATH = path.resolve(__dirname, "../../protos/dataceenevent.proto");
+let cachedPackage = null;
+function loadProto() {
+    if (cachedPackage)
+        return cachedPackage;
+    const packageDef = protoLoader.loadSync(PROTO_PATH, {
+        keepCase: true,
+        longs: String,
+        enums: String,
+        defaults: true,
+        oneofs: true,
+    });
+    cachedPackage = grpc.loadPackageDefinition(packageDef);
+    return cachedPackage;
+}
+/**
+ * gRPC host/port from a SubscriptionUrl config value like "https://subscription.dataceen.com".
+ * grpc-js wants `host:port`, not URL, so we strip scheme and default the port.
+ */
+export function subscriptionHost(subscriptionUrl) {
+    const u = new URL(subscriptionUrl);
+    const port = u.port || (u.protocol === "https:" ? "443" : "80");
+    return `${u.hostname}:${port}`;
+}
+/** Open a gRPC stream. Returns a stream object + a close() function. */
+export function openSubscriptionStream(opts) {
+    const pkg = loadProto();
+    const host = subscriptionHost(opts.subscriptionUrl);
+    const client = new pkg.dataceen.DataceenEvent(host, grpc.credentials.createSsl());
+    const metadata = new grpc.Metadata();
+    metadata.add("authorization", `Bearer ${opts.accessToken}`);
+    // Map our camelCased request to the proto's lowercase field names.
+    const r = opts.request;
+    const protoRequest = {
+        domain: r.domain,
+        model: r.model,
+        scope: r.scope,
+        baseloadtopics: r.baseloadTopics ?? [],
+        topics: r.topics,
+        ids: r.ids ?? [],
+        startmode: r.startMode ?? "POSITION_BEGINNING",
+        position: r.position ?? "",
+        starttime: r.startTime ? { seconds: Math.floor(r.startTime.getTime() / 1000), nanos: 0 } : undefined,
+        includedelta: r.includeDelta ?? false,
+        includecomplete: r.includeComplete ?? false,
+        baseloadcontinueobjecttype: r.baseloadContinueObjectType ?? "",
+        positionbeforebaseload: r.positionBeforeBaseload ?? "",
+    };
+    return client.Subscribe(protoRequest, metadata);
+}

package/dist/subscriptions/index.d.ts

@@ -0,0 +1,3 @@
+export { type StartMode, type MessageType, type EventType, type OperationType, type ObjectType, type SubscriptionRequest, type SubscriptionEventBase, type SubscriptionEvent, type SubscriptionLowLevelEvent, type EventHandler, type LowLevelEventHandler, } from "./types.js";
+export { Subscription } from "./subscription.js";
+export { runSubscription, type SubscriptionManagerOptions, } from "./subscription-manager.js";

package/dist/subscriptions/index.js

@@ -0,0 +1,2 @@
+export { Subscription } from "./subscription.js";
+export { runSubscription, } from "./subscription-manager.js";

package/dist/subscriptions/subscription-manager.d.ts

@@ -0,0 +1,26 @@
+import type { Logger } from "../config.js";
+import type { TokenProvider } from "../client/token-provider.js";
+import { type RawEventData } from "./grpc-client.js";
+import type { Subscription } from "./subscription.js";
+import type { SubscriptionLowLevelEvent } from "./types.js";
+export interface SubscriptionManagerOptions {
+    subscriptionUrl: string;
+    subscriptionScope: string;
+    tokenProvider: TokenProvider;
+    logger: Logger;
+    /** Warn when a handler takes longer than this (ms). Default 500. */
+    slowHandlerThresholdMs?: number;
+    /** Max reconnect attempts after a stream error. Default 10. */
+    maxReconnectAttempts?: number;
+    /** Base backoff (ms) for reconnects; doubles on each attempt. Default 1000. */
+    reconnectBaseMs?: number;
+}
+/**
+ * Run the subscription: open a gRPC stream, read events, dispatch to handlers,
+ * reconnect on transient errors, exit cleanly when the subscription is cancelled.
+ */
+export declare function runSubscription(subscription: Subscription, opts: SubscriptionManagerOptions): Promise<void>;
+/** @internal exposed for testing */
+export declare function dispatchOne(subscription: Subscription, lowLevel: SubscriptionLowLevelEvent, logger: Logger, slowMs: number): Promise<void>;
+/** @internal exposed for testing */
+export declare function toLowLevelEvent(raw: RawEventData): SubscriptionLowLevelEvent;