@o11y-one/sdk 0.0.0

package/dist/refusals.js

@@ -0,0 +1,125 @@
+/**
+ * The typed-refusal vocabulary.
+ *
+ * The generated messages carry refusal *kinds* as numeric proto enums. A caller
+ * branching on a bare number is a caller reading a magic constant, so this
+ * module lifts each one to its WIRE ENUM MEMBER NAME — the SCREAMING_SNAKE
+ * string the proto itself declares (`LEASE_EXPIRED`, `PREVIEW_MALFORMED`, …).
+ * No name is invented here: the reverse map of the generated `enum` is the
+ * single source, so this SDK and the Python SDK that mirrors it cannot drift
+ * apart or drift from the server.
+ *
+ * Each refusal is a small, flat, discriminated record: a `type` naming the
+ * refusal FAMILY (which verb refused), a `reason` naming the wire kind WITHIN
+ * that family, the structured fields the server attached, and `raw` — the
+ * untouched generated message — for the caller who needs a field this shape
+ * did not lift.
+ */
+import { ConnectError } from "@connectrpc/connect";
+import { ExternalLeaseRefusalKindV1, ExternalSubmissionAckKindV1, EvaluationLaunchRejectionKindV1, EvaluationCaptureRefusalKindV1, EvaluationDatasetVersionRejectionKindV1, EvaluationResyncReasonV1, PlatformAnnotationRejectionReasonV1, PlatformAnnotationKindV1, RecoveryActionV1, } from "@o11y-one/api-agentic/o11y_one/agentic/v1/evaluation_pb";
+/**
+ * The member name of a numeric proto enum value, e.g.
+ * `enumName(ExternalLeaseRefusalKindV1, 4)` → `"LEASE_EXPIRED"`. Unknown or
+ * absent values (a discriminant added server-side after this SDK was built)
+ * fold to `"UNSPECIFIED"` rather than a raw number, so a newer server never
+ * makes an older client emit a bare integer.
+ */
+function enumName(enumObj, value) {
+    return enumObj[value] ?? "UNSPECIFIED";
+}
+function recoveryName(value) {
+    if (value === undefined) {
+        return "UNSPECIFIED";
+    }
+    return enumName(RecoveryActionV1, value);
+}
+export function toLeaseRefusal(m) {
+    return {
+        type: "lease-refusal",
+        reason: enumName(ExternalLeaseRefusalKindV1, m.kind),
+        message: m.message,
+        missingScope: m.missingScope,
+        recovery: recoveryName(m.recovery),
+        raw: m,
+    };
+}
+export function toCaseAck(m) {
+    return {
+        cohortKey: m.cohortKey,
+        candidateKey: m.candidateKey,
+        caseRevisionId: m.caseRevisionId,
+        trial: m.trial,
+        kind: enumName(ExternalSubmissionAckKindV1, m.kind),
+        observedState: m.observedState,
+        raw: m,
+    };
+}
+export function toLaunchRejection(m) {
+    return {
+        type: "launch-rejection",
+        reason: enumName(EvaluationLaunchRejectionKindV1, m.kind),
+        expectedDigest: m.expectedDigest,
+        observedDigest: m.observedDigest,
+        existingEvaluationRunId: m.existingEvaluationRunId,
+        recovery: recoveryName(m.recovery),
+        detail: m.detail,
+        raw: m,
+    };
+}
+export function toCaptureRefusal(m) {
+    return {
+        type: "capture-refusal",
+        reason: enumName(EvaluationCaptureRefusalKindV1, m.kind),
+        detail: m.detail,
+        missingTargetPaths: m.missingTargetPaths,
+        recovery: recoveryName(m.recovery),
+        existingProposedCaseId: m.existingProposedCaseId,
+        raw: m,
+    };
+}
+export function toDatasetVersionRejection(m) {
+    return {
+        type: "dataset-version-rejection",
+        reason: enumName(EvaluationDatasetVersionRejectionKindV1, m.kind),
+        reasonCode: m.reasonCode,
+        lineNumber: m.lineNumber,
+        observedCount: m.observedCount,
+        maxCount: m.maxCount,
+        detail: m.detail,
+        recovery: recoveryName(m.recovery),
+        raw: m,
+    };
+}
+export function toAnnotationRejection(m) {
+    return {
+        type: "annotation-rejection",
+        reason: enumName(PlatformAnnotationRejectionReasonV1, m.reason),
+        field: m.field,
+        limitValue: m.limitValue,
+        supportedKinds: m.supportedKinds.map((k) => enumName(PlatformAnnotationKindV1, k)),
+        raw: m,
+    };
+}
+export function toCursorResync(m) {
+    return {
+        type: "cursor-resync",
+        reason: enumName(EvaluationResyncReasonV1, m.reason),
+        raw: m,
+    };
+}
+/**
+ * Pull the first typed detail of a given schema off a thrown error.
+ *
+ * This is how a refusal that rides in `google.rpc.Status.details` (launch,
+ * capture, dataset-version, annotation) is recovered: connect-es already
+ * decodes `Status.details`, and `ConnectError.findDetails(schema)` hands back
+ * the typed messages. A non-Connect error, or a Connect error with no such
+ * detail, returns `undefined` and the caller rethrows.
+ */
+export function findDetail(error, schema) {
+    if (!(error instanceof ConnectError)) {
+        return undefined;
+    }
+    const details = error.findDetails(schema);
+    return details.length > 0 ? details[0] : undefined;
+}

package/dist/result.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A `Result<T, E>` discriminated union.
+ *
+ * This is the SDK's answer to the compendium's key shape: many verbs on the
+ * agentic-evaluation surface refuse ON A 200 — the refusal is a field on the
+ * response message, not a transport error. Throwing on it would erase a typed,
+ * structured, actionable value and hand the caller a stack trace instead. So
+ * the journey methods that can be refused this way return a `Result`: `ok` on
+ * acceptance, `err` carrying a TYPED refusal the caller branches on.
+ *
+ * Errors that arrive as a transport failure (a real non-200 with a
+ * `google.rpc.Status`) are a different axis and still throw a `ConnectError` —
+ * `classify()` in errors.ts renders those. A method whose refusal rides in
+ * `Status.details` (launch, annotation, dataset-version) catches that throw and
+ * folds it back into an `err(...)` so the caller has ONE branch to write, not
+ * two. Which methods do which is documented on each.
+ */
+/** The acceptance arm. */
+export interface Ok<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+/** The refusal arm. `refusal` is always one of the typed unions in refusals.ts. */
+export interface Err<E> {
+    readonly ok: false;
+    readonly refusal: E;
+}
+export type Result<T, E> = Ok<T> | Err<E>;
+export declare function ok<T>(value: T): Ok<T>;
+export declare function err<E>(refusal: E): Err<E>;
+export declare function isOk<T, E>(r: Result<T, E>): r is Ok<T>;
+export declare function isErr<T, E>(r: Result<T, E>): r is Err<E>;
+/**
+ * Unwrap or throw. A convenience for scripts and tests that WANT the throw —
+ * the library itself never calls this. The thrown error names the refusal so a
+ * stack trace is still legible.
+ */
+export declare function unwrap<T, E>(r: Result<T, E>): T;

package/dist/result.js

@@ -0,0 +1,40 @@
+/**
+ * A `Result<T, E>` discriminated union.
+ *
+ * This is the SDK's answer to the compendium's key shape: many verbs on the
+ * agentic-evaluation surface refuse ON A 200 — the refusal is a field on the
+ * response message, not a transport error. Throwing on it would erase a typed,
+ * structured, actionable value and hand the caller a stack trace instead. So
+ * the journey methods that can be refused this way return a `Result`: `ok` on
+ * acceptance, `err` carrying a TYPED refusal the caller branches on.
+ *
+ * Errors that arrive as a transport failure (a real non-200 with a
+ * `google.rpc.Status`) are a different axis and still throw a `ConnectError` —
+ * `classify()` in errors.ts renders those. A method whose refusal rides in
+ * `Status.details` (launch, annotation, dataset-version) catches that throw and
+ * folds it back into an `err(...)` so the caller has ONE branch to write, not
+ * two. Which methods do which is documented on each.
+ */
+export function ok(value) {
+    return { ok: true, value };
+}
+export function err(refusal) {
+    return { ok: false, refusal };
+}
+export function isOk(r) {
+    return r.ok;
+}
+export function isErr(r) {
+    return !r.ok;
+}
+/**
+ * Unwrap or throw. A convenience for scripts and tests that WANT the throw —
+ * the library itself never calls this. The thrown error names the refusal so a
+ * stack trace is still legible.
+ */
+export function unwrap(r) {
+    if (r.ok) {
+        return r.value;
+    }
+    throw new Error(`o11y call was refused: ${JSON.stringify(r.refusal)}`);
+}

package/dist/validate.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Client-side input validation — the SDK's contract-guard.
+ *
+ * It fails FAST, SYNCHRONOUSLY, and TYPED, before a wire call is made, on the
+ * mistakes the server would otherwise turn into an opaque `INVALID_ARGUMENT` a
+ * round trip later: a missing required field, both arms of a mutually-exclusive
+ * oneof set at once (or neither), an `UNSPECIFIED` enum discriminant the server
+ * refuses, an idempotency key a CI retry forgot to mint.
+ *
+ * It is NOT the server's validation and never duplicates the authoritative
+ * byte-caps — those are published on the capability envelope and enforced
+ * server-side, and this layer surfaces the resulting typed rejection rather
+ * than second-guessing the number. What it checks is STRUCTURE the SDK can be
+ * certain of without the network.
+ */
+/**
+ * A local, pre-flight validation failure. `field` names the offending input in
+ * the caller's terms so the message is actionable without reading the proto.
+ */
+export declare class ValidationError extends Error {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+/** Trim-aware non-empty string check. */
+export declare function requireNonEmpty(field: string, value: string | undefined): string;
+/**
+ * An idempotency key the caller must supply. Required on every write that a CI
+ * job could retry — a retry that forgot its key is exactly how a run, a case,
+ * or a marker gets created twice.
+ */
+export declare function requireIdempotencyKey(field: string, value: string | undefined): string;
+/**
+ * Exactly-one-of, for a proto `oneof` the SDK exposes as separate arguments.
+ * `entries` lists each arm and whether the caller supplied it; zero or two-plus
+ * present is a `ValidationError` naming what was seen.
+ */
+export declare function requireExactlyOne(label: string, entries: ReadonlyArray<{
+    readonly name: string;
+    readonly present: boolean;
+}>): void;
+/**
+ * Reject an `UNSPECIFIED` (zero) discriminant in a set the server refuses
+ * outright. An `UNSPECIFIED` scope on a principal-create, or inside a list
+ * filter, is `INVALID_ARGUMENT` server-side; catching it here names the
+ * position instead of the whole call.
+ */
+export declare function rejectUnspecified(field: string, values: readonly number[]): void;
+/**
+ * UTF-8 byte length, for the size guards a caller can opt into. Computed
+ * without `TextEncoder` so this module pulls in neither the DOM lib nor
+ * `@types/node` — it runs identically in a browser, a Worker and Node.
+ */
+export declare function byteLength(value: string): number;
+/**
+ * An optional upper byte-bound. Used only where the SDK holds a published limit
+ * (e.g. the 128-byte credential cap in auth.ts); never with an invented number.
+ */
+export declare function requireWithinBytes(field: string, value: string, maxBytes: number): string;

package/dist/validate.js

@@ -0,0 +1,103 @@
+/**
+ * Client-side input validation — the SDK's contract-guard.
+ *
+ * It fails FAST, SYNCHRONOUSLY, and TYPED, before a wire call is made, on the
+ * mistakes the server would otherwise turn into an opaque `INVALID_ARGUMENT` a
+ * round trip later: a missing required field, both arms of a mutually-exclusive
+ * oneof set at once (or neither), an `UNSPECIFIED` enum discriminant the server
+ * refuses, an idempotency key a CI retry forgot to mint.
+ *
+ * It is NOT the server's validation and never duplicates the authoritative
+ * byte-caps — those are published on the capability envelope and enforced
+ * server-side, and this layer surfaces the resulting typed rejection rather
+ * than second-guessing the number. What it checks is STRUCTURE the SDK can be
+ * certain of without the network.
+ */
+/**
+ * A local, pre-flight validation failure. `field` names the offending input in
+ * the caller's terms so the message is actionable without reading the proto.
+ */
+export class ValidationError extends Error {
+    field;
+    constructor(field, message) {
+        super(message);
+        this.name = "ValidationError";
+        this.field = field;
+    }
+}
+/** Trim-aware non-empty string check. */
+export function requireNonEmpty(field, value) {
+    if (value === undefined || value.trim().length === 0) {
+        throw new ValidationError(field, `${field} is required and must not be empty`);
+    }
+    return value;
+}
+/**
+ * An idempotency key the caller must supply. Required on every write that a CI
+ * job could retry — a retry that forgot its key is exactly how a run, a case,
+ * or a marker gets created twice.
+ */
+export function requireIdempotencyKey(field, value) {
+    if (value === undefined || value.trim().length === 0) {
+        throw new ValidationError(field, `${field} is required: a retry-safe write needs a caller-minted idempotency key`);
+    }
+    return value;
+}
+/**
+ * Exactly-one-of, for a proto `oneof` the SDK exposes as separate arguments.
+ * `entries` lists each arm and whether the caller supplied it; zero or two-plus
+ * present is a `ValidationError` naming what was seen.
+ */
+export function requireExactlyOne(label, entries) {
+    const present = entries.filter((e) => e.present).map((e) => e.name);
+    if (present.length === 1) {
+        return;
+    }
+    const names = entries.map((e) => e.name).join(", ");
+    if (present.length === 0) {
+        throw new ValidationError(label, `exactly one of {${names}} is required — none was supplied`);
+    }
+    throw new ValidationError(label, `exactly one of {${names}} is allowed — got {${present.join(", ")}}`);
+}
+/**
+ * Reject an `UNSPECIFIED` (zero) discriminant in a set the server refuses
+ * outright. An `UNSPECIFIED` scope on a principal-create, or inside a list
+ * filter, is `INVALID_ARGUMENT` server-side; catching it here names the
+ * position instead of the whole call.
+ */
+export function rejectUnspecified(field, values) {
+    const at = values.indexOf(0);
+    if (at !== -1) {
+        throw new ValidationError(field, `${field}[${at}] is UNSPECIFIED (0); the server refuses an unspecified discriminant`);
+    }
+}
+/**
+ * UTF-8 byte length, for the size guards a caller can opt into. Computed
+ * without `TextEncoder` so this module pulls in neither the DOM lib nor
+ * `@types/node` — it runs identically in a browser, a Worker and Node.
+ */
+export function byteLength(value) {
+    let bytes = 0;
+    for (let i = 0; i < value.length; i++) {
+        const code = value.codePointAt(i);
+        if (code === undefined) {
+            continue;
+        }
+        if (code > 0xffff) {
+            i++; // a surrogate pair spans two UTF-16 code units
+        }
+        bytes += code <= 0x7f ? 1 : code <= 0x7ff ? 2 : code <= 0xffff ? 3 : 4;
+    }
+    return bytes;
+}
+/**
+ * An optional upper byte-bound. Used only where the SDK holds a published limit
+ * (e.g. the 128-byte credential cap in auth.ts); never with an invented number.
+ */
+export function requireWithinBytes(field, value, maxBytes) {
+    const len = byteLength(value);
+    if (len > maxBytes) {
+        throw new ValidationError(field, `${field} is ${len} bytes, over the ${maxBytes}-byte limit`);
+    }
+    return value;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@o11y-one/sdk",
+  "version": "0.0.0",
+  "description": "Hand-written client wrapper over @o11y-one/api-agentic: transport construction, credential injection, and the O11y One error taxonomy.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.15.0",
+    "@connectrpc/connect": "^2.2.0",
+    "@connectrpc/connect-node": "^2.2.0",
+    "@connectrpc/connect-web": "^2.2.0",
+    "@o11y-one/api-agentic": "0.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o11y-one/o11y-one-sdk.git",
+    "directory": "packages/sdk-ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test test/*.test.js",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}