@tarkahq/sdk 0.0.0-stage → 0.3.0

package/api-source.json

@@ -0,0 +1,38 @@
+{
+  "repository": "https://github.com/TarkaHQ/api",
+  "revision": "1bbe9c6ab8c1cdd73e4309b1ad062a44eb2964e9",
+  "generators": {
+    "grpc-tools": "1.13.1",
+    "ts-proto": "2.12.4"
+  },
+  "options": [
+    "outputServices=generic-definitions",
+    "outputClientImpl=false",
+    "env=node",
+    "forceLong=bigint",
+    "oneof=unions-value",
+    "useExactTypes=false",
+    "esModuleInterop=true",
+    "importSuffix=.js"
+  ],
+  "sources": {
+    "tarka/access/v1/access.proto": "aa8960b47aaaa3bfedf95d7e1060fa8b4c03601c15d67d1b365fa93c1d67d278",
+    "tarka/channels/v1/channels.proto": "9d5301f73af5f736389b6dfc66ce2bb8c87cc3f40f4ba22b87e94fbfe3385e47",
+    "tarka/gateway/v1/gateway.proto": "3490a2dc178d356e0748b933316650d2335579c48412de38048be0356f8dc6fe",
+    "tarka/iam/v1/iam.proto": "885f3fc0e7e7fd60f69e47891dfb734ae932ed33f2431b7f95e147185112daab",
+    "tarka/inference/v1/inference.proto": "7690975cde9687537511cb26bc32c83470ddde427c59c71670f52c68b4ee72f1",
+    "tarka/provisioning/v1/agent_secrets.proto": "b6c4774cd21609a6179b15851592ca9d71a8857e3a9c8a616694ff6c697c2540",
+    "tarka/provisioning/v1/billing_quote.proto": "ba69a5c0e922833fa4efcc0772e522483485fcb0e6d75ab4b0cd9e5d59db0e4c",
+    "tarka/provisioning/v1/job.proto": "e3bb52fdc2521a8e39255c02a8a62982dcf33803b20caa82fbf9da2b726d5175",
+    "tarka/provisioning/v1/provisioning.proto": "f227bb9426ede9345e71342f85700725278fbdcb7e12b6a40162ce164c3a9f0d",
+    "tarka/provisioning/v1/registry_credentials.proto": "30d9abf3e013ad42dfd9871a4ceef8ce996cff010227fa23bfc9f156f62b0e6e",
+    "tarka/provisioning/v1/sandbox.proto": "a840ceedaa3c494ef3987ef93ff6875b78a8f0f64dfda09af0ed39f66a9c44d7",
+    "tarka/provisioning/v1/source_builds.proto": "900d424f76533eabbede0d43c10bbcc9ffc8aaef85653f2b72e2c9d898a1fac6"
+  },
+  "imports": {
+    "google/api/annotations.proto": "e79ea741cb605a65e78ca322174764a4af9fde1962c1631e12b84c4934ba9a6c",
+    "google/api/http.proto": "ead99129aa15dd5f6233942030c72eec33bc0d7b1c7c260dc143293ef66c5b78",
+    "protoc-gen-openapiv2/options/annotations.proto": "1f8e23ce506c358349d5ce0e54c336e3b2f3bf17c5d9e7d965e24a6e3429c2c9",
+    "protoc-gen-openapiv2/options/openapiv2.proto": "8e9c28731f17e4608a1f7457cdd6f9a2718add4f5f9a0390dd5514a88e2023ef"
+  }
+}

package/dist/cjs/client.d.ts

@@ -0,0 +1,114 @@
+import type { ServiceClient } from "./transport.js";
+import { ChannelsServiceDefinition } from "./generated/tarka/channels/v1/channels.js";
+import { AccessServiceDefinition } from "./generated/tarka/access/v1/access.js";
+import { GatewayServiceDefinition } from "./generated/tarka/gateway/v1/gateway.js";
+import { IAMServiceDefinition } from "./generated/tarka/iam/v1/iam.js";
+import { Channel, type ChannelCredentials, type ChannelOptions } from "@grpc/grpc-js";
+import { InferenceServiceDefinition } from "./generated/tarka/inference/v1/inference.js";
+import { Audio, Catalog, Chat, Models, Ocr, Responses } from "./resources/inference.js";
+import { Users, Organizations, OrganizationScope, Git } from "./resources/provisioning.js";
+import { type GrpcClient, type ProvisioningRpc } from "./rpc-types.js";
+/** Default native gRPC endpoint used by authenticated SDK-owned connections. */
+export declare const DEFAULT_GRPC_ENDPOINT = "grpc.tarka.rest:443";
+/** Advanced gRPC endpoint and TLS configuration for an SDK-owned connection. */
+export interface ChannelConfig {
+    /** Native gRPC target, such as `grpc.tarka.rest:443`, or a resolver URI. Defaults to the Tarka endpoint; do not use an HTTP URL. */
+    target?: string;
+    /** TLS credentials, for example `credentials.createSsl(customRootCA)` imported from `@tarkahq/sdk/grpc`. */
+    channelCredentials?: ChannelCredentials;
+    /** Native grpc-js channel settings. Ordinary SDK use does not require them. */
+    channelOptions?: ChannelOptions;
+}
+/**
+ * Choose an access token with optional endpoint/TLS settings, or inject a caller-owned channel.
+ *
+ * An injected channel cannot be combined with a token or channel configuration. `timeoutMs` sets the default RPC timeout; sandbox wait helpers use their own total budget.
+ */
+export type TarkaClientOptions = ((ChannelConfig & {
+    /** Raw bearer token, without a Bearer prefix. The SDK configures TLS authentication. */
+    accessToken: string;
+    channel?: never;
+}) | {
+    /** Caller-owned connection; the caller supplies authentication and closes it. */
+    channel: Channel;
+    accessToken?: never;
+    target?: never;
+    channelCredentials?: never;
+    channelOptions?: never;
+}) & {
+    /** Default RPC timeout in milliseconds; per-call timeoutMs overrides it. Wait/run helpers default to their own 60-second total budget. */
+    timeoutMs?: number;
+};
+/**
+ * Create a TLS channel with bearer authentication. The caller owns its lifecycle.
+ *
+ * @param accessToken - Raw token without a `Bearer` prefix, whitespace, or control characters.
+ * @param options - Optional native gRPC target, TLS credentials, and channel settings.
+ * @returns A channel that must be closed by its owner.
+ * @throws TypeError for an invalid token or HTTP target. Insecure credentials cannot be combined with bearer authentication.
+ */
+export declare function createChannel(accessToken: string, options?: ChannelConfig): Channel;
+/**
+ * Tarka resource client for inference, organizations, compute, storage, Git, and sandboxes.
+ *
+ * Reuse one client across requests. Resource methods expose typed entities and TarkaError failures; advanced transport access is isolated under `grpc`.
+ * @example
+ * const client = new TarkaClient({ accessToken, timeoutMs: 30_000 });
+ * try {
+ *   const text = await client.chat.text({ model, prompt: "Hello" });
+ * } finally {
+ *   client.close();
+ * }
+ */
+export declare class TarkaClient {
+    #private;
+    /** Advanced native RPC clients and their shared channel. These retain generated envelopes, native call options, and numeric gRPC errors. */
+    readonly iam: ServiceClient<typeof IAMServiceDefinition>;
+    readonly gateway: ServiceClient<typeof GatewayServiceDefinition>;
+    readonly access: ServiceClient<typeof AccessServiceDefinition>;
+    readonly channels: ServiceClient<typeof ChannelsServiceDefinition>;
+    readonly control: ProvisioningRpc;
+    readonly inferenceApi: ServiceClient<typeof InferenceServiceDefinition>;
+    readonly grpc: GrpcClient;
+    /** Discover inference-visible models as plain records. */
+    readonly models: Models;
+    /** Typed completions, text helpers, and OpenAI-compatible JSON chat. */
+    readonly chat: Chat;
+    /** OpenAI-compatible Responses API with direct JSON bodies and events. */
+    readonly responses: Responses;
+    /** Image text recognition with full-result and text-only helpers. */
+    readonly ocr: Ocr;
+    /** Audio transcription, translation, speech generation, and voice cloning. */
+    readonly audio: Audio;
+    /** Control plane model catalog with modality filtering and provisioning details. */
+    readonly catalog: Catalog;
+    /** Retrieve or initialize the authenticated account. */
+    readonly user: Users;
+    /** List, retrieve, and create organizations. Use `org(id)` for organization-scoped resources. */
+    readonly organizations: Organizations;
+    /** Ensure hosted Git access for the authenticated account. */
+    readonly git: Git;
+    /**
+     * Create a resource client with a shared connection.
+     *
+     * @param options - Raw access token and optional RPC timeout, or a caller-owned channel. Defaults to TLS at grpc.tarka.rest:443.
+     * @throws TypeError for invalid or mutually exclusive connection options.
+     */
+    constructor(options: TarkaClientOptions);
+    /**
+     * Bind resource operations to one organization without making a network request.
+     *
+     * @param id - Organization identifier, for example `user.defaultOrgId`.
+     * @returns A scope whose nested operations automatically include this organization ID.
+     * @example
+     * const org = client.org(orgId);
+     * const keys = await org.apiKeys.list();
+     */
+    org(id: string): OrganizationScope;
+    /**
+     * Close the SDK-owned connection. Safe to call more than once.
+     *
+     * A caller-provided channel remains open and must be closed by its owner. Close after active work has finished, typically on application shutdown.
+     */
+    close(): void;
+}

package/dist/cjs/client.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TarkaClient = exports.DEFAULT_GRPC_ENDPOINT = void 0;
+exports.createChannel = createChannel;
+const channels_js_1 = require("./generated/tarka/channels/v1/channels.js");
+const access_js_1 = require("./generated/tarka/access/v1/access.js");
+const gateway_js_1 = require("./generated/tarka/gateway/v1/gateway.js");
+const iam_js_1 = require("./generated/tarka/iam/v1/iam.js");
+const grpc_js_1 = require("@grpc/grpc-js");
+const inference_js_1 = require("./generated/tarka/inference/v1/inference.js");
+const provisioning_js_1 = require("./generated/tarka/provisioning/v1/provisioning.js");
+const sandbox_js_1 = require("./generated/tarka/provisioning/v1/sandbox.js");
+const transport_js_1 = require("./transport.js");
+const inference_js_2 = require("./resources/inference.js");
+const provisioning_js_2 = require("./resources/provisioning.js");
+const rpc_types_js_1 = require("./rpc-types.js");
+/** Default native gRPC endpoint used by authenticated SDK-owned connections. */
+exports.DEFAULT_GRPC_ENDPOINT = "grpc.tarka.rest:443";
+/**
+ * Create a TLS channel with bearer authentication. The caller owns its lifecycle.
+ *
+ * @param accessToken - Raw token without a `Bearer` prefix, whitespace, or control characters.
+ * @param options - Optional native gRPC target, TLS credentials, and channel settings.
+ * @returns A channel that must be closed by its owner.
+ * @throws TypeError for an invalid token or HTTP target. Insecure credentials cannot be combined with bearer authentication.
+ */
+function createChannel(accessToken, options = {}) {
+    if (typeof accessToken !== "string" || !/^[\x21-\x7e]+$/.test(accessToken)) {
+        throw new TypeError("accessToken must be a non-empty token without whitespace or control characters");
+    }
+    const target = options.target ?? exports.DEFAULT_GRPC_ENDPOINT;
+    if (!target.trim() || /^https?:\/\//i.test(target)) {
+        throw new TypeError("target must be a native gRPC target such as grpc.tarka.rest:443");
+    }
+    const auth = grpc_js_1.credentials.createFromMetadataGenerator((_params, callback) => {
+        const metadata = new grpc_js_1.Metadata();
+        metadata.set("authorization", `Bearer ${accessToken}`);
+        callback(null, metadata);
+    });
+    // grpc-js rejects combining call credentials with an insecure channel.
+    const secure = grpc_js_1.credentials.combineChannelCredentials(options.channelCredentials ?? grpc_js_1.credentials.createSsl(), auth);
+    return new grpc_js_1.Channel(target, secure, options.channelOptions ?? {});
+}
+/**
+ * Tarka resource client for inference, organizations, compute, storage, Git, and sandboxes.
+ *
+ * Reuse one client across requests. Resource methods expose typed entities and TarkaError failures; advanced transport access is isolated under `grpc`.
+ * @example
+ * const client = new TarkaClient({ accessToken, timeoutMs: 30_000 });
+ * try {
+ *   const text = await client.chat.text({ model, prompt: "Hello" });
+ * } finally {
+ *   client.close();
+ * }
+ */
+class TarkaClient {
+    /** Advanced native RPC clients and their shared channel. These retain generated envelopes, native call options, and numeric gRPC errors. */
+    iam;
+    gateway;
+    access;
+    channels;
+    control;
+    inferenceApi;
+    grpc;
+    /** Discover inference-visible models as plain records. */
+    models;
+    /** Typed completions, text helpers, and OpenAI-compatible JSON chat. */
+    chat;
+    /** OpenAI-compatible Responses API with direct JSON bodies and events. */
+    responses;
+    /** Image text recognition with full-result and text-only helpers. */
+    ocr;
+    /** Audio transcription, translation, speech generation, and voice cloning. */
+    audio;
+    /** Control plane model catalog with modality filtering and provisioning details. */
+    catalog;
+    /** Retrieve or initialize the authenticated account. */
+    user;
+    /** List, retrieve, and create organizations. Use `org(id)` for organization-scoped resources. */
+    organizations;
+    /** Ensure hosted Git access for the authenticated account. */
+    git;
+    #provisioning;
+    #sandboxes;
+    #ownsChannel;
+    #closed = false;
+    /**
+     * Create a resource client with a shared connection.
+     *
+     * @param options - Raw access token and optional RPC timeout, or a caller-owned channel. Defaults to TLS at grpc.tarka.rest:443.
+     * @throws TypeError for invalid or mutually exclusive connection options.
+     */
+    constructor(options) {
+        if (!options || typeof options !== "object") {
+            throw new TypeError("TarkaClient requires an accessToken or a caller-provided channel");
+        }
+        (0, transport_js_1.validateTimeout)(options.timeoutMs);
+        let channel;
+        if (options.channel != null) {
+            if (options.accessToken !== undefined ||
+                options.target !== undefined ||
+                options.channelCredentials !== undefined ||
+                options.channelOptions !== undefined) {
+                throw new TypeError("A caller-provided channel cannot be combined with accessToken or channel configuration");
+            }
+            this.#ownsChannel = false;
+            channel = options.channel;
+        }
+        else {
+            this.#ownsChannel = true;
+            channel = createChannel(options.accessToken, options);
+        }
+        const defaults = { timeoutMs: options.timeoutMs };
+        const inference = (0, transport_js_1.createServiceClient)(inference_js_1.InferenceServiceDefinition, channel, defaults);
+        const provisioning = (0, transport_js_1.createServiceClient)(provisioning_js_1.ProvisioningServiceDefinition, channel, defaults);
+        const sandboxRpc = (0, transport_js_1.createServiceClient)(sandbox_js_1.SandboxServiceDefinition, channel, defaults);
+        const iam = (0, transport_js_1.createServiceClient)(iam_js_1.IAMServiceDefinition, channel, defaults);
+        this.iam = (0, rpc_types_js_1.sdkService)(iam_js_1.IAMServiceDefinition, iam);
+        const gateway = (0, transport_js_1.createServiceClient)(gateway_js_1.GatewayServiceDefinition, channel, defaults);
+        this.gateway = (0, rpc_types_js_1.sdkService)(gateway_js_1.GatewayServiceDefinition, gateway);
+        const access = (0, transport_js_1.createServiceClient)(access_js_1.AccessServiceDefinition, channel, defaults);
+        this.access = (0, rpc_types_js_1.sdkService)(access_js_1.AccessServiceDefinition, access);
+        const channels = (0, transport_js_1.createServiceClient)(channels_js_1.ChannelsServiceDefinition, channel, defaults);
+        this.channels = (0, rpc_types_js_1.sdkService)(channels_js_1.ChannelsServiceDefinition, channels);
+        this.grpc = Object.freeze({
+            channel,
+            inference,
+            provisioning,
+            iam,
+            gateway,
+            access,
+            channels,
+            sandboxes: sandboxRpc,
+        });
+        const inferenceSdk = (0, rpc_types_js_1.sdkService)(inference_js_1.InferenceServiceDefinition, inference);
+        this.inferenceApi = inferenceSdk;
+        this.#provisioning = (0, rpc_types_js_1.sdkService)(provisioning_js_1.ProvisioningServiceDefinition, provisioning);
+        this.control = this.#provisioning;
+        this.#sandboxes = (0, rpc_types_js_1.sdkService)(sandbox_js_1.SandboxServiceDefinition, sandboxRpc);
+        this.models = new inference_js_2.Models(inferenceSdk);
+        this.chat = new inference_js_2.Chat(inferenceSdk);
+        this.responses = new inference_js_2.Responses(inferenceSdk);
+        this.ocr = new inference_js_2.Ocr(inferenceSdk);
+        this.audio = new inference_js_2.Audio(inferenceSdk);
+        this.catalog = new inference_js_2.Catalog(this.#provisioning);
+        this.user = new provisioning_js_2.Users(this.#provisioning);
+        this.organizations = new provisioning_js_2.Organizations(this.#provisioning);
+        this.git = new provisioning_js_2.Git(this.#provisioning);
+    }
+    /**
+     * Bind resource operations to one organization without making a network request.
+     *
+     * @param id - Organization identifier, for example `user.defaultOrgId`.
+     * @returns A scope whose nested operations automatically include this organization ID.
+     * @example
+     * const org = client.org(orgId);
+     * const keys = await org.apiKeys.list();
+     */
+    org(id) {
+        return new provisioning_js_2.OrganizationScope(this.#provisioning, this.#sandboxes, id);
+    }
+    /**
+     * Close the SDK-owned connection. Safe to call more than once.
+     *
+     * A caller-provided channel remains open and must be closed by its owner. Close after active work has finished, typically on application shutdown.
+     */
+    close() {
+        if (this.#ownsChannel && !this.#closed) {
+            this.grpc.channel.close();
+            this.#closed = true;
+        }
+    }
+}
+exports.TarkaClient = TarkaClient;

package/dist/cjs/errors.d.ts

@@ -0,0 +1,27 @@
+import type { Metadata } from "./types.js";
+/** Stable string error codes used by resource methods. Native numeric gRPC codes are exposed only by `client.grpc`. */
+export type ErrorCode = "cancelled" | "unknown" | "invalid_argument" | "deadline_exceeded" | "not_found" | "already_exists" | "permission_denied" | "resource_exhausted" | "failed_precondition" | "aborted" | "out_of_range" | "unimplemented" | "internal" | "unavailable" | "data_loss" | "unauthenticated";
+/**
+ * A resource API failure with a readable message, stable string code, and plain metadata.
+ *
+ * The underlying error is available through `cause`. Local argument validation throws TypeError; sandbox operation errors additionally expose explicit recovery.
+ * @example
+ * if (error instanceof TarkaError && error.code === "deadline_exceeded") {
+ *   console.error("Client wait expired");
+ * }
+ */
+export declare class TarkaError extends Error {
+    /** Stable string code, such as deadline_exceeded or permission_denied. */
+    readonly code: ErrorCode;
+    constructor(message: string, 
+    /** Stable string code, such as deadline_exceeded or permission_denied. */
+    code: ErrorCode, options?: {
+        cause?: unknown;
+        metadata?: Metadata;
+    });
+    /** Trailing server metadata as a plain object, or an empty object when no trailers are available. */
+    readonly metadata: Metadata;
+}
+export declare function normalizeError(error: unknown): TarkaError;
+export declare function required<T>(value: T | undefined, field: string): T;
+export declare function requireText(value: unknown, name: string): asserts value is string;

package/dist/cjs/errors.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TarkaError = void 0;
+exports.normalizeError = normalizeError;
+exports.required = required;
+exports.requireText = requireText;
+const grpc_js_1 = require("@grpc/grpc-js");
+const codes = [
+    "unknown",
+    "cancelled",
+    "unknown",
+    "invalid_argument",
+    "deadline_exceeded",
+    "not_found",
+    "already_exists",
+    "permission_denied",
+    "resource_exhausted",
+    "failed_precondition",
+    "aborted",
+    "out_of_range",
+    "unimplemented",
+    "internal",
+    "unavailable",
+    "data_loss",
+    "unauthenticated",
+];
+/**
+ * A resource API failure with a readable message, stable string code, and plain metadata.
+ *
+ * The underlying error is available through `cause`. Local argument validation throws TypeError; sandbox operation errors additionally expose explicit recovery.
+ * @example
+ * if (error instanceof TarkaError && error.code === "deadline_exceeded") {
+ *   console.error("Client wait expired");
+ * }
+ */
+class TarkaError extends Error {
+    code;
+    constructor(message, 
+    /** Stable string code, such as deadline_exceeded or permission_denied. */
+    code, options = {}) {
+        super(message, { cause: options.cause });
+        this.code = code;
+        this.name = "TarkaError";
+        this.metadata = options.metadata ?? {};
+    }
+    /** Trailing server metadata as a plain object, or an empty object when no trailers are available. */
+    metadata;
+}
+exports.TarkaError = TarkaError;
+function normalizeError(error) {
+    if (error instanceof TarkaError)
+        return error;
+    if (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "number") {
+        const details = "details" in error && typeof error.details === "string"
+            ? error.details
+            : "Tarka request failed";
+        const metadata = "metadata" in error && error.metadata instanceof grpc_js_1.Metadata
+            ? error.metadata.getMap()
+            : {};
+        return new TarkaError(details, codes[error.code] ?? "unknown", {
+            cause: error,
+            metadata,
+        });
+    }
+    return new TarkaError(error instanceof Error ? error.message : "Tarka request failed", "unknown", { cause: error });
+}
+function required(value, field) {
+    if (value === undefined)
+        throw new TarkaError(`The server response is missing ${field}`, "data_loss");
+    return value;
+}
+function requireText(value, name) {
+    if (typeof value !== "string" || !value.trim())
+        throw new TypeError(`${name} must not be empty`);
+}

package/dist/cjs/generated/google/api/annotations.d.ts

@@ -0,0 +1 @@
+export declare const protobufPackage = "google.api";

package/dist/cjs/generated/google/api/annotations.js

@@ -0,0 +1,10 @@
+"use strict";
+// Code generated by protoc-gen-ts_proto. DO NOT EDIT.
+// versions:
+//   protoc-gen-ts_proto  v2.12.4
+//   protoc               v3.19.1
+// source: google/api/annotations.proto
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.protobufPackage = void 0;
+/* eslint-disable */
+exports.protobufPackage = "google.api";