dataceen-client 0.0.1

package/LICENSE

@@ -0,0 +1,16 @@
+Copyright (c) 2026 Dataceen AB.
+
+All rights reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+modification, distribution, or use of this software, via any medium, is
+strictly prohibited without the express written permission of the copyright
+holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
+FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# dataceen-client (TypeScript)
+
+TypeScript client for the Dataceen GraphQL + gRPC subscription APIs. Parallel
+to the C# (`DataceenClient/`) and Python (`DataceenClientPython/`) reference
+clients — feature-parity verified against the same `Thomas/CandyShopModel/All`
+fixtures.
+
+> **Status:** 0.0.1 alpha.
+
+## Install
+
+```sh
+npm install dataceen-client
+```
+
+## Usage
+
+```ts
+import { DataceenClient } from "dataceen-client";
+import { DataceenConfig } from "dataceen-client/config";
+
+const config = new DataceenConfig({
+  tenantId: process.env.DATACEEN_TENANT_ID!,
+  clientId: process.env.DATACEEN_CLIENT_ID!,
+  clientSecret: process.env.DATACEEN_CLIENT_SECRET!,
+  baseUrl: process.env.DATACEEN_BASE_URL!,
+});
+
+const client = new DataceenClient(config);
+```
+
+Subpath entry points:
+
+| Import | Purpose |
+| --- | --- |
+| `dataceen-client` | Top-level client + query API |
+| `dataceen-client/config` | Configuration types |
+| `dataceen-client/runtime` | Transport / auth runtime |
+| `dataceen-client/subscriptions` | gRPC baseload + live subscriptions |
+
+## Build from source
+
+```sh
+npm install
+npm run build   # emits dist/ (.js + .d.ts) via tsconfig.build.json
+```
+
+## License
+
+Proprietary — see [LICENSE](./LICENSE).

package/dist/client/dataceen-client.d.ts

@@ -0,0 +1,47 @@
+import { type DataceenClientOptions, type DataceenConfig } from "../config.js";
+import { type GqlRequest } from "./http-transport.js";
+import { Subscription } from "../subscriptions/subscription.js";
+import { type SubscriptionManagerOptions } from "../subscriptions/subscription-manager.js";
+import type { SubscriptionRequest } from "../subscriptions/types.js";
+export interface ExecuteOptions {
+    /**
+     * Override the default retryOnTransient for this call.
+     * Defaults: query = true, mutation = false.
+     */
+    retryOnTransient?: boolean;
+}
+/**
+ * Low-level client — ports the HTTP/token surface of C# DataceenClient.cs.
+ * Typed per-entity methods (findCustomerNodes, etc.) will be generated in fase 3.
+ */
+export declare class DataceenClient {
+    readonly config: DataceenConfig;
+    private readonly logger;
+    private readonly tokenProvider;
+    private readonly transport;
+    private readonly slowHandlerThresholdMs;
+    private subscriptionCounter;
+    constructor(config: DataceenConfig, options?: DataceenClientOptions);
+    /**
+     * Create a subscription that can be populated with handlers and then
+     * activated with `subscribe()`. Fills in domain/model/scope from config
+     * if the caller omits them.
+     */
+    createSubscription(request: Omit<SubscriptionRequest, "domain" | "model" | "scope"> & Partial<Pick<SubscriptionRequest, "domain" | "model" | "scope">>): Subscription;
+    /**
+     * Activate a subscription: opens the gRPC stream and dispatches events to
+     * registered handlers until the subscription is cancelled or the stream
+     * errors fatally.
+     *
+     * Resolves cleanly when the subscription is cancelled; rejects if reconnects
+     * are exhausted.
+     */
+    subscribe(subscription: Subscription, overrides?: Partial<SubscriptionManagerOptions>): Promise<void>;
+    /** Execute a GraphQL query. Retries on transient errors by default. */
+    executeQuery<T = unknown>(req: GqlRequest, options?: ExecuteOptions): Promise<T>;
+    /**
+     * Execute a GraphQL mutation. Does NOT retry transient errors by default —
+     * mutations are not idempotent without server-side idempotency keys.
+     */
+    executeMutation<T = unknown>(req: GqlRequest, options?: ExecuteOptions): Promise<T>;
+}

package/dist/client/dataceen-client.js

@@ -0,0 +1,122 @@
+import { consoleLogger, } from "../config.js";
+import { DataceenError } from "./errors.js";
+import { HttpTransport } from "./http-transport.js";
+import { TokenProvider } from "./token-provider.js";
+import { Subscription } from "../subscriptions/subscription.js";
+import { runSubscription, } from "../subscriptions/subscription-manager.js";
+/**
+ * Low-level client — ports the HTTP/token surface of C# DataceenClient.cs.
+ * Typed per-entity methods (findCustomerNodes, etc.) will be generated in fase 3.
+ */
+export class DataceenClient {
+    config;
+    logger;
+    tokenProvider;
+    transport;
+    slowHandlerThresholdMs;
+    subscriptionCounter = 0;
+    constructor(config, options = {}) {
+        this.config = config;
+        this.logger = options.logger ?? consoleLogger;
+        this.slowHandlerThresholdMs = options.slowHandlerThresholdMs ?? 500;
+        this.tokenProvider = new TokenProvider(config);
+        const apiPath = `${config.apiPath}/${config.domain}/${config.model}/${config.scope}`;
+        this.transport = new HttpTransport({
+            apiUrl: config.apiUrl,
+            apiPath,
+            apiScope: config.apiScope,
+            tokenProvider: this.tokenProvider,
+            logger: this.logger,
+            httpTimeoutMs: options.httpTimeoutMs,
+            maxTransientRetries: options.maxTransientRetries,
+            transientRetryBaseMs: options.transientRetryBaseMs,
+        });
+    }
+    /**
+     * Create a subscription that can be populated with handlers and then
+     * activated with `subscribe()`. Fills in domain/model/scope from config
+     * if the caller omits them.
+     */
+    createSubscription(request) {
+        this.subscriptionCounter++;
+        const id = `sub-${this.subscriptionCounter}`;
+        const full = {
+            domain: request.domain ?? this.config.domain,
+            model: request.model ?? this.config.model,
+            scope: request.scope ?? this.config.scope,
+            topics: request.topics,
+            baseloadTopics: request.baseloadTopics,
+            ids: request.ids,
+            startMode: request.startMode,
+            position: request.position,
+            startTime: request.startTime,
+            includeDelta: request.includeDelta,
+            includeComplete: request.includeComplete,
+            baseloadContinueObjectType: request.baseloadContinueObjectType,
+            positionBeforeBaseload: request.positionBeforeBaseload,
+        };
+        return new Subscription(id, full);
+    }
+    /**
+     * Activate a subscription: opens the gRPC stream and dispatches events to
+     * registered handlers until the subscription is cancelled or the stream
+     * errors fatally.
+     *
+     * Resolves cleanly when the subscription is cancelled; rejects if reconnects
+     * are exhausted.
+     */
+    async subscribe(subscription, overrides = {}) {
+        return runSubscription(subscription, {
+            subscriptionUrl: this.config.subscriptionUrl,
+            subscriptionScope: this.config.subscriptionScope,
+            tokenProvider: this.tokenProvider,
+            logger: this.logger,
+            slowHandlerThresholdMs: this.slowHandlerThresholdMs,
+            ...overrides,
+        });
+    }
+    /** Execute a GraphQL query. Retries on transient errors by default. */
+    async executeQuery(req, options = {}) {
+        const retry = options.retryOnTransient ?? true;
+        const text = await this.transport.postGraphQL(req, retry);
+        return parseGraphQLResponse(text, req);
+    }
+    /**
+     * Execute a GraphQL mutation. Does NOT retry transient errors by default —
+     * mutations are not idempotent without server-side idempotency keys.
+     */
+    async executeMutation(req, options = {}) {
+        const retry = options.retryOnTransient ?? false;
+        const text = await this.transport.postGraphQL(req, retry);
+        return parseGraphQLResponse(text, req);
+    }
+}
+/**
+ * Parse a GraphQL response body:
+ *   1. JSON-parse the envelope
+ *   2. If `errors` present, throw
+ *   3. Extract `data[operationName]`
+ *   4. If payload has ResponseCode != 0, throw (Dataceen server-side error)
+ *   5. Return payload as T
+ */
+function parseGraphQLResponse(text, req) {
+    let envelope;
+    try {
+        envelope = JSON.parse(text);
+    }
+    catch (ex) {
+        throw new DataceenError(`Failed to parse response as JSON: ${ex.message}. Raw: ${text.slice(0, 500)}`, -1, req.query, ex);
+    }
+    if (envelope.errors && envelope.errors.length > 0) {
+        throw new DataceenError(`GraphQL errors: ${envelope.errors.map((e) => e.message).join("; ")}`, -1, req.query);
+    }
+    const payload = envelope.data?.[req.operationName];
+    if (payload == null) {
+        throw new DataceenError(`Response does not contain data.${req.operationName}. Raw: ${text.slice(0, 500)}`, -1, req.query);
+    }
+    const coded = payload;
+    if (coded.ResponseCode != null && coded.ResponseCode !== 0) {
+        throw new DataceenError(coded.Message ?? `ResponseCode=${coded.ResponseCode}`, coded.ResponseCode, req.query);
+    }
+    return payload;
+}

package/dist/client/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Raised for any failure inside the Dataceen client pipeline:
+ * HTTP non-success responses, GraphQL errors, server-side ResponseCode != 0,
+ * JSON parse failures, and transport errors that exhausted retries.
+ *
+ * Mirrors the C# DataceenException with its HResult/SourceQuery fields.
+ */
+export declare class DataceenError extends Error {
+    /**
+     * Server-side ResponseCode if available, the negated HTTP status as a fallback,
+     * or -1 for client-side failures (JSON parse, envelope shape).
+     */
+    readonly responseCode: number;
+    readonly sourceQuery?: string;
+    constructor(message: string, responseCode: number, sourceQuery?: string, cause?: unknown);
+}

package/dist/client/errors.js

@@ -0,0 +1,26 @@
+/**
+ * Raised for any failure inside the Dataceen client pipeline:
+ * HTTP non-success responses, GraphQL errors, server-side ResponseCode != 0,
+ * JSON parse failures, and transport errors that exhausted retries.
+ *
+ * Mirrors the C# DataceenException with its HResult/SourceQuery fields.
+ */
+export class DataceenError extends Error {
+    /**
+     * Server-side ResponseCode if available, the negated HTTP status as a fallback,
+     * or -1 for client-side failures (JSON parse, envelope shape).
+     */
+    responseCode;
+    sourceQuery;
+    constructor(message, responseCode, sourceQuery, cause) {
+        super(message);
+        this.name = "DataceenError";
+        this.responseCode = responseCode;
+        this.sourceQuery = sourceQuery;
+        if (cause !== undefined) {
+            // Node 16.9+ supports Error.cause via the constructor, but we assign it
+            // explicitly to keep compatibility with older targets too.
+            Object.defineProperty(this, "cause", { value: cause, enumerable: false });
+        }
+    }
+}

package/dist/client/http-transport.d.ts

@@ -0,0 +1,33 @@
+import type { Logger } from "../config.js";
+import type { TokenProviderLike } from "./token-provider.js";
+export interface GqlRequest {
+    operationName: string;
+    query: string;
+}
+export interface HttpTransportOptions {
+    apiUrl: string;
+    /** Full path including domain/model/scope suffix. */
+    apiPath: string;
+    apiScope: string;
+    tokenProvider: TokenProviderLike;
+    logger: Logger;
+    httpTimeoutMs?: number;
+    maxTransientRetries?: number;
+    transientRetryBaseMs?: number;
+}
+/**
+ * Ports the resilience logic from C# DataceenClient.PostGraphQLAsync:
+ *   - one forced token refresh on HTTP 401, retry once
+ *   - optional transient retry (network errors + 408/429/5xx) with exponential backoff
+ */
+export declare class HttpTransport {
+    private readonly opts;
+    private readonly endpoint;
+    private readonly timeoutMs;
+    private readonly maxTransient;
+    private readonly retryBaseMs;
+    constructor(opts: HttpTransportOptions);
+    /** POST a GraphQL request and return the raw response body. */
+    postGraphQL(req: GqlRequest, retryOnTransient: boolean): Promise<string>;
+    private fetchWithTimeout;
+}

package/dist/client/http-transport.js

@@ -0,0 +1,100 @@
+import { DataceenError } from "./errors.js";
+/**
+ * Ports the resilience logic from C# DataceenClient.PostGraphQLAsync:
+ *   - one forced token refresh on HTTP 401, retry once
+ *   - optional transient retry (network errors + 408/429/5xx) with exponential backoff
+ */
+export class HttpTransport {
+    opts;
+    endpoint;
+    timeoutMs;
+    maxTransient;
+    retryBaseMs;
+    constructor(opts) {
+        this.opts = opts;
+        this.endpoint = `${opts.apiUrl}${opts.apiPath}`;
+        this.timeoutMs = opts.httpTimeoutMs ?? 60_000;
+        this.maxTransient = opts.maxTransientRetries ?? 3;
+        this.retryBaseMs = opts.transientRetryBaseMs ?? 200;
+    }
+    /** POST a GraphQL request and return the raw response body. */
+    async postGraphQL(req, retryOnTransient) {
+        const body = JSON.stringify(req);
+        const maxTransient = retryOnTransient ? this.maxTransient : 0;
+        let transientAttempt = 0;
+        let triedAuthRefresh = false;
+        let delayMs = this.retryBaseMs;
+        while (true) {
+            const token = await this.opts.tokenProvider.getAccessToken([this.opts.apiScope], triedAuthRefresh);
+            let res;
+            try {
+                res = await this.fetchWithTimeout(body, token);
+            }
+            catch (ex) {
+                if (transientAttempt < maxTransient) {
+                    transientAttempt++;
+                    const msg = ex instanceof Error ? ex.message : String(ex);
+                    this.opts.logger.log("warn", `Transient HTTP error (attempt ${transientAttempt}/${maxTransient}): ${msg}. Retrying in ${delayMs}ms.`);
+                    await delay(delayMs);
+                    delayMs *= 2;
+                    continue;
+                }
+                throw ex;
+            }
+            if (res.status === 401 && !triedAuthRefresh) {
+                triedAuthRefresh = true;
+                this.opts.logger.log("warn", "401 Unauthorized — forcing token refresh and retrying once.");
+                await drain(res);
+                continue;
+            }
+            if (retryOnTransient &&
+                !res.ok &&
+                isTransientStatus(res.status) &&
+                transientAttempt < maxTransient) {
+                transientAttempt++;
+                this.opts.logger.log("warn", `Transient HTTP status ${res.status} (attempt ${transientAttempt}/${maxTransient}). Retrying in ${delayMs}ms.`);
+                await drain(res);
+                await delay(delayMs);
+                delayMs *= 2;
+                continue;
+            }
+            const text = await res.text();
+            if (!res.ok) {
+                throw new DataceenError(`HTTP ${res.status}: ${text.slice(0, 500)}`, -res.status, req.query);
+            }
+            return text;
+        }
+    }
+    async fetchWithTimeout(body, token) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            return await fetch(this.endpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${token}`,
+                },
+                body,
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+function isTransientStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function drain(res) {
+    try {
+        await res.text();
+    }
+    catch {
+        // ignore — only called to release the connection before a retry
+    }
+}

package/dist/client/index.d.ts

@@ -0,0 +1,5 @@
+export { DataceenClient, type ExecuteOptions } from "./dataceen-client.js";
+export { DataceenError } from "./errors.js";
+export { HttpTransport, type GqlRequest, type HttpTransportOptions } from "./http-transport.js";
+export { TokenProvider, type TokenProviderConfig, type TokenProviderLike } from "./token-provider.js";
+export type { FindResult, SearchResult, QueryResult, RequestResult, MutationResult, SingleMutationResult, FindByIdResult, } from "./types.js";

package/dist/client/index.js

@@ -0,0 +1,4 @@
+export { DataceenClient } from "./dataceen-client.js";
+export { DataceenError } from "./errors.js";
+export { HttpTransport } from "./http-transport.js";
+export { TokenProvider } from "./token-provider.js";

package/dist/client/token-provider.d.ts

@@ -0,0 +1,22 @@
+export interface TokenProviderConfig {
+    tenantId: string;
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * Minimal TypeScript port of the C# TokenProvider.
+ * Uses MSAL's ConfidentialClientApplication (client-credentials flow).
+ */
+export declare class TokenProvider {
+    private readonly cca;
+    constructor(config: TokenProviderConfig);
+    /**
+     * Acquires an access token for the given scopes. When forceRefresh is true,
+     * bypasses MSAL's internal cache (mirrors C#'s AcquireTokenForClient().WithForceRefresh(true)).
+     */
+    getAccessToken(scopes: string[], forceRefresh?: boolean): Promise<string>;
+}
+/** Minimal interface used by HttpTransport — lets tests supply a fake. */
+export interface TokenProviderLike {
+    getAccessToken(scopes: string[], forceRefresh?: boolean): Promise<string>;
+}

package/dist/client/token-provider.js

@@ -0,0 +1,31 @@
+import { ConfidentialClientApplication } from "@azure/msal-node";
+/**
+ * Minimal TypeScript port of the C# TokenProvider.
+ * Uses MSAL's ConfidentialClientApplication (client-credentials flow).
+ */
+export class TokenProvider {
+    cca;
+    constructor(config) {
+        this.cca = new ConfidentialClientApplication({
+            auth: {
+                clientId: config.clientId,
+                clientSecret: config.clientSecret,
+                authority: `https://login.microsoftonline.com/${config.tenantId}`,
+            },
+        });
+    }
+    /**
+     * Acquires an access token for the given scopes. When forceRefresh is true,
+     * bypasses MSAL's internal cache (mirrors C#'s AcquireTokenForClient().WithForceRefresh(true)).
+     */
+    async getAccessToken(scopes, forceRefresh = false) {
+        const result = await this.cca.acquireTokenByClientCredential({
+            scopes,
+            skipCache: forceRefresh,
+        });
+        if (!result?.accessToken) {
+            throw new Error("acquireTokenByClientCredential returned no accessToken");
+        }
+        return result.accessToken;
+    }
+}

package/dist/client/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * GraphQL result shapes.
+ *
+ * Field names use PascalCase to match the wire format from the Dataceen server
+ * (e.g. the server returns `{ "Items": [...], "Cursor": "..." }`).
+ * Decision deferred to fase 2 whether to transform to camelCase in the client.
+ */
+export interface FindResult<T> {
+    Items: T[];
+    Cursor: string;
+    ResponseTime: number;
+    ResponseCode: number;
+    Message: string;
+}
+export interface SearchResult<T> {
+    Items: T[];
+    Cursor: string;
+    ResponseTime: number;
+    /**
+     * Aggregation results — populated when the search request included an
+     * `aggregations` argument. Each entry matches the shape of the runtime's
+     * `Aggregation` type. Not advertised in GraphQL introspection but returned
+     * by the server when asked for in the selection.
+     */
+    Aggregations: unknown[];
+    ResponseCode: number;
+    Message: string;
+}
+export interface QueryResult<T> {
+    Response: T;
+    _id: string;
+    ResponseTime: number;
+    ResponseCode: number;
+    Message: string;
+}
+export interface RequestResult<T> {
+    Response: T;
+    _id: string;
+    ResponseTime: number;
+    ResponseCode: number;
+    Message: string;
+}
+export interface MutationResult {
+    Result: string[];
+    ResponseTime: number;
+    ResponseCode: number;
+    Message: string;
+}
+export interface SingleMutationResult {
+    Result: string;
+    ResponseTime: number;
+}
+export interface FindByIdResult<T> {
+    Item: T | undefined;
+    ResponseTime: number;
+}

package/dist/client/types.js

@@ -0,0 +1,8 @@
+/**
+ * GraphQL result shapes.
+ *
+ * Field names use PascalCase to match the wire format from the Dataceen server
+ * (e.g. the server returns `{ "Items": [...], "Cursor": "..." }`).
+ * Decision deferred to fase 2 whether to transform to camelCase in the client.
+ */
+export {};

package/dist/config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Configuration for a DataceenClient instance.
+ * Mirrors the values under e.g. "AllClient" in the C# example's appsettings.json.
+ */
+export interface DataceenConfig {
+    tenantId: string;
+    clientId: string;
+    clientSecret: string;
+    domain: string;
+    model: string;
+    scope: string;
+    /** Base URL, e.g. "https://api.dataceen.com" (no trailing slash). */
+    apiUrl: string;
+    /** Path prefix, e.g. "/graphql". domain/model/scope are appended by the client. */
+    apiPath: string;
+    /** OAuth scope for the GraphQL endpoint, e.g. "api://.../.default". */
+    apiScope: string;
+    /** Base URL for the gRPC subscription service. */
+    subscriptionUrl: string;
+    /** OAuth scope for the subscription service. */
+    subscriptionScope: string;
+}
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface Logger {
+    log(level: LogLevel, message: string, error?: unknown): void;
+}
+/** Default logger that writes to console with a [dataceen-client] prefix. */
+export declare const consoleLogger: Logger;
+/** Logger that silently discards all messages. Useful in tests. */
+export declare const silentLogger: Logger;
+export interface DataceenClientOptions {
+    logger?: Logger;
+    /** HTTP request timeout in ms. Default: 60_000. */
+    httpTimeoutMs?: number;
+    /** Max transient retries (when retryOnTransient is true). Default: 3. */
+    maxTransientRetries?: number;
+    /** Base backoff in ms; doubles on each retry. Default: 200. */
+    transientRetryBaseMs?: number;
+    /** Warn when a subscription handler takes longer than this (ms). Default: 500. */
+    slowHandlerThresholdMs?: number;
+}

package/dist/config.js

@@ -0,0 +1,19 @@
+/** Default logger that writes to console with a [dataceen-client] prefix. */
+export const consoleLogger = {
+    log(level, message, error) {
+        const prefix = `[dataceen-client] [${level}]`;
+        if (error !== undefined) {
+            console.error(prefix, message, error);
+        }
+        else if (level === "error" || level === "warn") {
+            console.error(prefix, message);
+        }
+        else {
+            console.log(prefix, message);
+        }
+    },
+};
+/** Logger that silently discards all messages. Useful in tests. */
+export const silentLogger = {
+    log() { },
+};