@cowliss/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bogdan Radu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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,60 @@
+# @cowliss/sdk
+
+The TypeScript client for the Cowliss ingestion API. Send `identify` and
+`track` from your app, and Cowliss keeps the profiles, the events, the
+segments, and the journeys that follow from them.
+
+Runs anywhere `fetch` does: Node 22 and up, Bun, Deno, edge runtimes and
+browsers. Zero dependencies, ESM only, fully typed.
+
+## Install
+
+```sh
+npm install @cowliss/sdk
+```
+
+## Use it
+
+```ts
+import { Cow } from "@cowliss/sdk";
+
+const cow = new Cow({
+  apiKey: process.env.COW_API_KEY!,
+  sourceId: process.env.COW_SOURCE_ID!,
+  baseUrl: "https://api.cowliss.com",
+});
+
+await cow.identify({
+  identifiers: { userId: "u_1", email: "ada@example.com" },
+  traits: { plan: "pro" },
+});
+
+await cow.track({
+  identifiers: { userId: "u_1" },
+  event: "checkout.completed",
+  properties: { amount: 4900, currency: "usd" },
+});
+```
+
+Every call carries `identifiers`, a map from kind to value. Cowliss generates
+the profile id and resolves the map to it, so a call that carries two
+identifiers is what links two profiles. There is no alias call.
+
+`identify` returns the profile, `track` returns the stored event, and
+`batch` imports many of both in one request for backfills. Each call names
+the source it arrives through: set `sourceId` once on the client, or pass one
+per call when a single process writes into more than one app.
+
+Retries are handled for you. A call that fails to reach Cowliss, or that
+Cowliss could not complete, backs off and tries twice more; a generated
+`messageId` travels with every track, so a retry after a lost response never
+writes the event twice. A call Cowliss rejected is not retried: it throws a
+`CowError` carrying the reason.
+
+## Docs
+
+[docs.cowliss.com](https://docs.cowliss.com)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+import type { BatchBody, BatchResultDto, ErrorCode, EventDto, IdentifyInput, ProfileDto, TrackInput } from "./types.js";
+export type * from "./types.js";
+/**
+ * The Cowliss TS client SDK. Small typed surface over the ingestion API:
+ * cow.identify / .track / .batch. Every call carries `identifiers` (a map
+ * from kind to value; Cowliss generates the profile id and resolves them), so
+ * there is no alias call: linking happens whenever one call carries two
+ * identifiers. Every call also names the source it arrives through: give the
+ * constructor a `sourceId` and the calls inherit it, or name one per call
+ * when one process writes into more than one app. messageIds are generated
+ * automatically (and double as the Idempotency-Key, so a retry after a lost
+ * response dedupes instead of double-writing); network errors and 5xx retry with exponential backoff;
+ * 4xx surface as typed CowErrors with the API's error-code enum, never
+ * retried.
+ */
+export declare class CowError extends Error {
+    readonly code: ErrorCode | "network_error";
+    readonly status: number;
+    constructor(code: ErrorCode | "network_error", message: string, status: number, options?: {
+        cause?: unknown;
+    });
+}
+export type CowOptions = {
+    /** Org ingestion API key ("Bearer" credential on every request). */
+    apiKey: string;
+    /**
+     * The `src_` source every call arrives through, when the caller does not
+     * name one per call. An app's source is a deployment fact, not a per-call
+     * one, so the common case is one client per app configured once here; a
+     * process that writes into two apps passes `sourceId` per call (or holds
+     * two clients) and this default stays out of the way.
+     */
+    sourceId?: string;
+    /** API origin, no trailing slash. Defaults to local dev. */
+    baseUrl?: string;
+    /** Retries after the initial attempt on network errors / 5xx. Default 2. */
+    maxRetries?: number;
+    /** Injectable for tests and non-fetch runtimes. */
+    fetch?: typeof globalThis.fetch;
+};
+/**
+ * The per-call shape: `sourceId` is optional here and required on the wire,
+ * so a client constructed with one takes calls without it. `#sourceFor`
+ * puts it back before the request, or fails naming both ways to supply it.
+ */
+type WithDefaultSource<T extends {
+    sourceId: string;
+}> = Omit<T, "sourceId"> & {
+    sourceId?: string;
+};
+export declare class Cow {
+    #private;
+    constructor(options: CowOptions);
+    identify(input: WithDefaultSource<IdentifyInput>): Promise<ProfileDto>;
+    /**
+     * Tracks one event. A messageId is generated when the caller does not
+     * supply one, and sent both in the body and as the Idempotency-Key, so a
+     * retried request (network error, 5xx, or lost response) dedupes
+     * server-side. Historical timestamps pass through for backfill scripts.
+     */
+    track(input: WithDefaultSource<TrackInput>): Promise<EventDto>;
+    /**
+     * Batch import: one source's identify and track calls in one request.
+     * Track items must carry an explicit messageId: the API requires it and
+     * the SDK does not generate one here, so re-running the same backfill
+     * (same messageIds) dedupes instead of double-writing.
+     */
+    batch(input: WithDefaultSource<BatchBody["data"]>): Promise<BatchResultDto>;
+}

package/dist/index.js

@@ -0,0 +1,113 @@
+import { CLIENT_HEADER, SDK_VERSION } from "./types.js";
+/** What this client calls itself in {@link CLIENT_HEADER}. */
+const CLIENT_ID = `@cowliss/sdk/${SDK_VERSION}`;
+/**
+ * The Cowliss TS client SDK. Small typed surface over the ingestion API:
+ * cow.identify / .track / .batch. Every call carries `identifiers` (a map
+ * from kind to value; Cowliss generates the profile id and resolves them), so
+ * there is no alias call: linking happens whenever one call carries two
+ * identifiers. Every call also names the source it arrives through: give the
+ * constructor a `sourceId` and the calls inherit it, or name one per call
+ * when one process writes into more than one app. messageIds are generated
+ * automatically (and double as the Idempotency-Key, so a retry after a lost
+ * response dedupes instead of double-writing); network errors and 5xx retry with exponential backoff;
+ * 4xx surface as typed CowErrors with the API's error-code enum, never
+ * retried.
+ */
+export class CowError extends Error {
+    code;
+    status;
+    constructor(code, message, status, options) {
+        super(message, options);
+        this.name = "CowError";
+        this.code = code;
+        this.status = status;
+    }
+}
+const RETRY_BASE_DELAY_MS = 100;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class Cow {
+    #apiKey;
+    #sourceId;
+    #baseUrl;
+    #maxRetries;
+    #fetch;
+    constructor(options) {
+        this.#apiKey = options.apiKey;
+        this.#sourceId = options.sourceId;
+        this.#baseUrl = options.baseUrl ?? "http://localhost:3400";
+        this.#maxRetries = options.maxRetries ?? 2;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+    }
+    /**
+     * The call's own `sourceId`, else the client's. Throws when neither, from
+     * inside an async method so the caller sees a rejected promise like every
+     * other failure rather than a synchronous throw a `.catch()` would miss.
+     */
+    #sourceFor(input) {
+        const sourceId = input.sourceId ?? this.#sourceId;
+        if (!sourceId) {
+            throw new CowError("validation_failed", "No sourceId: pass one to the Cow constructor, or name one on the call.", 0);
+        }
+        return sourceId;
+    }
+    async identify(input) {
+        return this.#post("/v1/identify", {
+            data: { ...input, sourceId: this.#sourceFor(input) },
+        });
+    }
+    /**
+     * Tracks one event. A messageId is generated when the caller does not
+     * supply one, and sent both in the body and as the Idempotency-Key, so a
+     * retried request (network error, 5xx, or lost response) dedupes
+     * server-side. Historical timestamps pass through for backfill scripts.
+     */
+    async track(input) {
+        const messageId = input.messageId ?? crypto.randomUUID();
+        return this.#post("/v1/track", { data: { ...input, sourceId: this.#sourceFor(input), messageId } }, messageId);
+    }
+    /**
+     * Batch import: one source's identify and track calls in one request.
+     * Track items must carry an explicit messageId: the API requires it and
+     * the SDK does not generate one here, so re-running the same backfill
+     * (same messageIds) dedupes instead of double-writing.
+     */
+    async batch(input) {
+        return this.#post("/v1/batch", {
+            data: { ...input, sourceId: this.#sourceFor(input) },
+        });
+    }
+    async #post(path, body, idempotencyKey) {
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.#fetch(`${this.#baseUrl}${path}`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${this.#apiKey}`,
+                        "Content-Type": "application/json",
+                        [CLIENT_HEADER]: CLIENT_ID,
+                        ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
+                    },
+                    body: JSON.stringify(body),
+                });
+            }
+            catch (cause) {
+                if (attempt < this.#maxRetries) {
+                    await sleep(RETRY_BASE_DELAY_MS * 2 ** attempt);
+                    continue;
+                }
+                throw new CowError("network_error", "Network error", 0, { cause });
+            }
+            if (res.ok) {
+                return (await res.json()).data;
+            }
+            if (res.status >= 500 && attempt < this.#maxRetries) {
+                await sleep(RETRY_BASE_DELAY_MS * 2 ** attempt);
+                continue;
+            }
+            const parsed = (await res.json().catch(() => null));
+            throw new CowError(parsed?.error?.code ?? "internal", parsed?.error?.message ?? `Request failed with status ${res.status}`, res.status);
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The SDK's public types, hand-declared.
+ *
+ * They mirror `@cowliss/shared`, and they do not import it. The shared ones
+ * are `z.infer` over drizzle-zod schemas, so a declaration that referenced
+ * them would make drizzle-orm a type dependency of an ingestion client and
+ * would name a package a customer has never installed (which `skipLibCheck`
+ * would degrade to `any` in silence rather than report). Plain object types
+ * keep the SDK's `dist` free of both.
+ *
+ * `types.check.ts` asserts each of these is mutually assignable with the
+ * shared type it mirrors, so a wire-shape change fails the monorepo
+ * typecheck here rather than at a customer's call site.
+ */
+/** The API's error-code enum, as the SDK surfaces it on `CowError.code`. */
+export type ErrorCode = "malformed_request" | "invalid_key" | "forbidden" | "not_found" | "conflict" | "payload_too_large" | "validation_failed" | "trait_validation_failed" | "event_denied" | "trait_denied" | "over_quota" | "rate_limited" | "dependency_unavailable" | "internal" | "journey_fuel_exceeded" | "journey_timeout" | "journey_memory_exceeded" | "journey_error" | "journey_output_invalid" | "journey_nondeterministic" | "release_invalid" | "release_not_ready" | "project_exists" | "project_missing" | "artifact_too_large" | "deploy_key_scope";
+export type Environment = "development" | "production";
+export type IdentifierKind = "anonymousId" | "userId" | "clerkId" | "email";
+/**
+ * The named identifiers a call carries, at least one. Cowliss generates the
+ * profile id and resolves the map to it; a call carrying two identifiers is
+ * what links two profiles, so there is no alias call.
+ */
+export type Identifiers = Partial<Record<IdentifierKind, string>>;
+export type IdentifierDto = {
+    kind: IdentifierKind;
+    value: string;
+    createdAt: string;
+};
+/** A person, as identify returns them. */
+export type ProfileDto = {
+    id: string;
+    orgId: string;
+    environment: Environment;
+    /** The app that first created the profile. */
+    appId: string;
+    /** The source the creating write arrived through. */
+    sourceId: string;
+    traits: Record<string, unknown>;
+    consent: Record<string, boolean>;
+    /** Set on a profile that was merged away, naming the survivor. */
+    mergedInto: string | null;
+    createdAt: string;
+    updatedAt: string;
+    identifiers: IdentifierDto[];
+    /** True when every identifier is an anonymousId. */
+    anonymous: boolean;
+};
+/** One stored event, as track returns it. */
+export type EventDto = {
+    id: string;
+    orgId: string;
+    environment: Environment;
+    appId: string;
+    sourceId: string;
+    profileId: string;
+    event: string;
+    properties: Record<string, unknown>;
+    timestamp: string;
+    receivedAt: string;
+    messageId: string | null;
+};
+export type IdentifyInput = {
+    sourceId: string;
+    identifiers: Identifiers;
+    traits?: Record<string, unknown>;
+    /** ISO 8601 UTC. A past timestamp backdates a first-write profile. */
+    timestamp?: string;
+    messageId?: string;
+};
+export type TrackInput = {
+    sourceId: string;
+    identifiers: Identifiers;
+    event: string;
+    properties?: Record<string, unknown>;
+    /** ISO 8601 UTC. A past timestamp is the event time, for backfill. */
+    timestamp?: string;
+    /** Generated by the SDK when omitted; also sent as the Idempotency-Key. */
+    messageId?: string;
+};
+/** One batch item: an identify or a track, minus the batch's own source. */
+export type BatchItem = ({
+    type: "identify";
+} & Omit<IdentifyInput, "sourceId">) | ({
+    type: "track";
+} & Omit<TrackInput, "sourceId"> & {
+    messageId: string;
+});
+export type BatchBody = {
+    data: {
+        sourceId: string;
+        /**
+         * Validated per item server-side, so one bad row never fails the import:
+         * the wire schema accepts anything here and reports item problems in the
+         * response. `BatchItem` is what a caller should send.
+         */
+        items: unknown[];
+    };
+};
+export type BatchItemResult = {
+    ok: true;
+    type: "identify";
+    id: string;
+} | {
+    ok: true;
+    type: "track";
+    id: string;
+    deduped: boolean;
+} | {
+    ok: false;
+    error: {
+        code: ErrorCode;
+        message: string;
+    };
+};
+export type BatchResultDto = {
+    results: BatchItemResult[];
+};
+/**
+ * The two runtime constants in this file, and the reason they live beside
+ * the types rather than in `@cowliss/shared`: this module is the SDK's one
+ * mirror of the shared vocabulary (`docs/standards/code.md`, "Central
+ * constants"), because a published package may not name an unpublished one.
+ *
+ * `CLIENT_HEADER` is pinned against the shared constant by `types.check.ts`.
+ * `SDK_VERSION` mirrors this package's own `version` instead, which no
+ * compiler can read from here: `apps/api/src/sdk.test.ts` is what fails when
+ * a release bumps one and not the other.
+ */
+export declare const CLIENT_HEADER = "X-Cow-Client";
+export declare const SDK_VERSION = "0.1.0";

package/dist/types.js

@@ -0,0 +1,27 @@
+/**
+ * The SDK's public types, hand-declared.
+ *
+ * They mirror `@cowliss/shared`, and they do not import it. The shared ones
+ * are `z.infer` over drizzle-zod schemas, so a declaration that referenced
+ * them would make drizzle-orm a type dependency of an ingestion client and
+ * would name a package a customer has never installed (which `skipLibCheck`
+ * would degrade to `any` in silence rather than report). Plain object types
+ * keep the SDK's `dist` free of both.
+ *
+ * `types.check.ts` asserts each of these is mutually assignable with the
+ * shared type it mirrors, so a wire-shape change fails the monorepo
+ * typecheck here rather than at a customer's call site.
+ */
+/**
+ * The two runtime constants in this file, and the reason they live beside
+ * the types rather than in `@cowliss/shared`: this module is the SDK's one
+ * mirror of the shared vocabulary (`docs/standards/code.md`, "Central
+ * constants"), because a published package may not name an unpublished one.
+ *
+ * `CLIENT_HEADER` is pinned against the shared constant by `types.check.ts`.
+ * `SDK_VERSION` mirrors this package's own `version` instead, which no
+ * compiler can read from here: `apps/api/src/sdk.test.ts` is what fails when
+ * a release bumps one and not the other.
+ */
+export const CLIENT_HEADER = "X-Cow-Client";
+export const SDK_VERSION = "0.1.0";

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@cowliss/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@cowliss/shared": "0.0.0",
+    "@types/node": "^26.2.0"
+  },
+  "description": "TypeScript client for the Cowliss ingestion API: identify, track and batch.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bogdanrn/cowliss.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://docs.cowliss.com",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.json --force",
+    "typecheck": "tsc -b tsconfig.json tsconfig.check.json"
+  }
+}