@tracon/client 1.0.0-preview.1

package/LICENSE.md

@@ -0,0 +1,164 @@
+# Tracon License
+
+Tracon is licensed under the **PolyForm Small Business License 1.0.0**. The
+canonical text follows below and is reproduced without modification.
+
+Required Notice: Copyright (c) 2026 Faruk Atasoy (https://tracon.dev)
+
+## Are you free to use it?
+
+Yes, at no cost, if your company has fewer than 100 total individuals working as
+employees and independent contractors, and less than 1,000,000 USD (2019, adjusted
+for inflation) total revenue in the prior tax year. An individual, a student and an
+open source project are all under that threshold. The exact wording is in the
+**Small Business** section below, which is the clause that governs.
+
+Above that threshold, use of Tracon needs a commercial licence. Write to
+hfarukatasoy@gmail.com.
+
+## Three packages are MIT instead
+
+| Package | Why it is MIT |
+|---------|---------------|
+| `Tracon.Abstractions` | Contracts only. A third party writes an extension against these interfaces; nothing here runs an agent. |
+| `Tracon.Testing.Contracts.Xunit` | The behaviour contract suites that an extension has to pass. It depends only on `Tracon.Abstractions`. |
+| `Tracon.Templates` | `dotnet new tracon-api` generates source into your project. The code it generates is yours, under no obligation to these terms. |
+
+Those three ship `LICENSE-MIT.md`. Every other package ships this file. A package
+states its own licence in its `.nuspec`; if the two ever disagree, the file inside
+the package governs.
+
+## There is no licence key
+
+No package contains an activation call, a licence check, a phone-home request or a
+feature gate. Nothing stops you from running Tracon. Compliance is yours to
+determine, the same way it is for any dependency your build already carries.
+
+## A published version keeps its licence
+
+The licence of a version that is already on NuGet never changes. Re-licensing, if
+it ever happens, applies to versions published after that point.
+
+---
+
+# PolyForm Small Business License 1.0.0
+
+<https://polyformproject.org/licenses/small-business/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## Small Business
+
+Use of the software for the benefit of your company is use for
+a permitted purpose if your company has fewer than 100 total
+individuals working as employees and independent contractors,
+and less than 1,000,000 USD (2019) total revenue in the prior
+tax year.  Adjust this revenue threshold for inflation according
+to the United States Bureau of Labor Statistics' consumer price
+index for all urban consumers, U.S. city average, for all items,
+not seasonally adjusted, with 1982–1984=100 reference base.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,105 @@
+# @tracon/client
+
+A typed TypeScript client for Tracon's management API, generated from its
+published [OpenAPI document](https://tracon.dev/openapi/tracon.json).
+Covers every `/api/*` and `/v1/*` operation: agents, runs, sessions, evals,
+workflows, tenants, and the rest of the control plane. Built on
+[`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/) — the only runtime
+dependency.
+
+```bash
+npm install @tracon/client
+```
+
+## Setup
+
+```ts
+import { createTraconClient } from '@tracon/client';
+
+const client = createTraconClient({
+  // The application root PLUS the MapTracon prefix. The default prefix
+  // is "/tracon"; an app that called MapTracon("/control") needs
+  // "https://example.com/control" instead.
+  baseUrl: 'https://example.com/tracon',
+  token: 'a-secret-token', // or a function called per request
+  onUnauthorized: () => {
+    /* the server answered 401 — your app decides what that means */
+  },
+});
+
+const { data: agents } = await client.GET('/api/agents');
+```
+
+Every call is typed against the OpenAPI document: the path, its parameters,
+its request body, and its response are all checked at compile time. A schema
+type is also exported by name for every schema in the document, so a
+response can be typed without indexing into `components`:
+
+```ts
+import type { RunRecord } from '@tracon/client';
+```
+
+## Errors are thrown, not returned
+
+`openapi-fetch` on its own returns `{ data, error }`. This package wraps it so
+a failed response instead **throws** `TraconError` — a request either
+resolves with `data` or the call rejects:
+
+```ts
+import { TraconError } from '@tracon/client';
+
+try {
+  await client.GET('/api/agents/{name}', { params: { path: { name: 'missing' } } });
+} catch (error) {
+  if (error instanceof TraconError) {
+    console.error(error.status, error.title, error.detail);
+  }
+}
+```
+
+`title` and `detail` come from the server's `application/problem+json` body
+and are shown verbatim — this package does not translate them.
+
+## What this package does not cover
+
+- **Server-Sent Events.** Six operations (agent `run`, workflow
+  `run`/`resume`/`respond`, and the OpenAI-compatible `responses` and
+  `chat/completions` endpoints) answer `text/event-stream`, not JSON. A
+  `fetch`-based typed client reads a response body as JSON; call these with
+  your own `EventSource`/`fetch` streaming code instead, using this
+  package's `paths` types for the request shape.
+- **Token storage.** This package reads a token you supply — it does not
+  read or write `localStorage`, a cookie, or anything else. Store it however
+  your application already does.
+
+## Why the base URL needs the prefix
+
+`MapTracon`'s prefix is a runtime parameter, not a fixed value — the
+document this package is generated from carries no prefix at all (it is
+stripped as part of the generation step). If requests went to the document's
+bare paths, a consumer that moved the mount point off the default
+`/tracon` would get a silent `404` on every call. `baseUrl` is where the
+prefix goes instead.
+
+## Regenerating
+
+```bash
+npm run generate   # docs/openapi/tracon.json -> src/schema.ts (committed)
+npm run build       # tsc -> dist/
+```
+
+`npm run generate` is a development step; it is not part of `npm run build`
+and is not called by `dotnet build`. Run it after `docs/openapi/tracon.json`
+changes, and commit the result — `npm test`'s `schema-drift` check fails the
+build otherwise.
+
+## Links
+
+- Guide: <https://tracon.dev/guides/typescript-client/>
+- `Tracon.Client` (the .NET counterpart, same document, same shape): <https://tracon.dev/api/>
+- Capability map: <https://tracon.dev/capabilities/>
+
+License: PolyForm Small Business 1.0.0, the same terms as its .NET counterpart
+`Tracon.Client` - free below 100 people and 1,000,000 USD (2019, inflation
+adjusted) revenue; a commercial licence applies above that. The text ships in this
+package as LICENSE.md. Details: <https://tracon.dev/reference/licensing/>

package/dist/client.d.ts

@@ -0,0 +1,26 @@
+import { type Client } from 'openapi-fetch';
+import type { paths } from './schema.js';
+/** Options for {@link createTraconClient}. */
+export interface TraconClientOptions {
+    /** Application root plus the prefix passed to `MapTracon` (default `/tracon`). */
+    baseUrl: string;
+    /** Bearer token, or a function that supplies one per request. */
+    token?: string | (() => string | null);
+    /** Called when the server answers 401 — the caller decides what "reject the token" means. */
+    onUnauthorized?: () => void;
+    /** Custom fetch, defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/** A client typed against every Tracon management API path. */
+export type TraconClient = Client<paths>;
+/**
+ * Creates a typed client that throws {@link TraconError} on a failed
+ * response.
+ *
+ * This layer stores no token itself — the caller's own token store (or a
+ * closure over one) is passed as `token`, and this layer only reads it. It
+ * does not translate `title`/`detail` (K-232): they come from the server and
+ * are shown verbatim.
+ */
+export declare function createTraconClient(options: TraconClientOptions): TraconClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAqB,EAAE,KAAK,MAAM,EAAmB,MAAM,eAAe,CAAC;AAC3E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGzC,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC;IACvC,6FAA6F;IAC7F,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,+DAA+D;AAC/D,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;AAOzC;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CA+C7E"}

package/dist/client.js

@@ -0,0 +1,51 @@
+import createClient, {} from 'openapi-fetch';
+import { TraconError } from './error.js';
+/**
+ * Creates a typed client that throws {@link TraconError} on a failed
+ * response.
+ *
+ * This layer stores no token itself — the caller's own token store (or a
+ * closure over one) is passed as `token`, and this layer only reads it. It
+ * does not translate `title`/`detail` (K-232): they come from the server and
+ * are shown verbatim.
+ */
+export function createTraconClient(options) {
+    const client = createClient({
+        baseUrl: options.baseUrl,
+        fetch: options.fetch,
+    });
+    const middleware = {
+        onRequest({ request }) {
+            const token = typeof options.token === 'function' ? options.token() : options.token;
+            if (token) {
+                request.headers.set('Authorization', `Bearer ${token}`);
+            }
+            return request;
+        },
+        async onResponse({ response }) {
+            if (response.ok) {
+                return response;
+            }
+            if (response.status === 401) {
+                // The token was rejected. The caller decides what that means (drop it,
+                // prompt again); this layer still throws below so the failed call does
+                // not silently resolve with no data.
+                options.onUnauthorized?.();
+            }
+            let title = `HTTP ${response.status}`;
+            let detail = null;
+            try {
+                const body = (await response.clone().json());
+                title = body.title ?? title;
+                detail = body.detail ?? null;
+            }
+            catch {
+                // A body that is not problem+json leaves the status line as the message.
+            }
+            throw new TraconError(response.status, title, detail);
+        },
+    };
+    client.use(middleware);
+    return client;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,EAAE,EAAgC,MAAM,eAAe,CAAC;AAE3E,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAsBzC;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC7D,MAAM,MAAM,GAAG,YAAY,CAAQ;QACjC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC,CAAC;IAEH,MAAM,UAAU,GAAe;QAC7B,SAAS,CAAC,EAAE,OAAO,EAAE;YACnB,MAAM,KAAK,GAAG,OAAO,OAAO,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;YAEpF,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,KAAK,EAAE,CAAC,CAAC;YAC1D,CAAC;YAED,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE;YAC3B,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;gBAChB,OAAO,QAAQ,CAAC;YAClB,CAAC;YAED,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBAC5B,uEAAuE;gBACvE,uEAAuE;gBACvE,qCAAqC;gBACrC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC;YAC7B,CAAC;YAED,IAAI,KAAK,GAAG,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;YACtC,IAAI,MAAM,GAAkB,IAAI,CAAC;YAEjC,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAuB,CAAC;gBAEnE,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC;gBAC5B,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC;YAC/B,CAAC;YAAC,MAAM,CAAC;gBACP,yEAAyE;YAC3E,CAAC;YAED,MAAM,IAAI,WAAW,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QACxD,CAAC;KACF,CAAC;IAEF,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAEvB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/error.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A failed request, carrying the server's own explanation.
+ *
+ * The management API answers with `application/problem+json` (decision
+ * K-038), so `title` and `detail` are written for a human and are shown
+ * verbatim (K-232) — this layer does not translate them.
+ */
+export declare class TraconError extends Error {
+    readonly status: number;
+    readonly title: string;
+    readonly detail: string | null;
+    constructor(status: number, title: string, detail: string | null);
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEnB,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;CAOjE"}

package/dist/error.js

@@ -0,0 +1,20 @@
+/**
+ * A failed request, carrying the server's own explanation.
+ *
+ * The management API answers with `application/problem+json` (decision
+ * K-038), so `title` and `detail` are written for a human and are shown
+ * verbatim (K-232) — this layer does not translate them.
+ */
+export class TraconError extends Error {
+    status;
+    title;
+    detail;
+    constructor(status, title, detail) {
+        super(detail ? `${title}: ${detail}` : title);
+        this.name = 'TraconError';
+        this.status = status;
+        this.title = title;
+        this.detail = detail;
+    }
+}
+//# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,MAAM,CAAS;IACf,KAAK,CAAS;IACd,MAAM,CAAgB;IAE/B,YAAY,MAAc,EAAE,KAAa,EAAE,MAAqB;QAC9D,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './schema.js';
+import type { components } from './schema.js';
+/** Wire contracts, by schema name. Example: `Schemas['RunRecord']`. */
+export type Schemas = components['schemas'];
+export { TraconError } from './error.js';
+export { createTraconClient, type TraconClient, type TraconClientOptions } from './client.js';
+export { readSse, SseDecoder, SseIdleTimeoutError, type ReadSseOptions, type SseFrame, } from './sse.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAC;AAE5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,uEAAuE;AACvE,MAAM,MAAM,OAAO,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;AAG5C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAM9F,OAAO,EACL,OAAO,EACP,UAAU,EACV,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,QAAQ,GACd,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+// Generated — every path, operation and schema, including a readable
+// root-level type alias per schema (e.g. `RunRecord`, `AgentDefinition`).
+export * from './schema.js';
+// Hand-written — the thin layer described in docs/arsiv/fazlar/84-TYPESCRIPT-ISTEMCISI-VE-NPM.md, section 84.5.
+export { TraconError } from './error.js';
+export { createTraconClient } from './client.js';
+// Streaming. A `text/event-stream` endpoint needs no special client method —
+// pass `parseAs: 'stream'`, or read the `response` every call returns — but it
+// does need a decoder, and writing one per consumer is how framing bugs get
+// duplicated (Phase 159).
+export { readSse, SseDecoder, SseIdleTimeoutError, } from './sse.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,0EAA0E;AAC1E,cAAc,aAAa,CAAC;AAO5B,gHAAgH;AAChH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAA+C,MAAM,aAAa,CAAC;AAE9F,6EAA6E;AAC7E,+EAA+E;AAC/E,4EAA4E;AAC5E,0BAA0B;AAC1B,OAAO,EACL,OAAO,EACP,UAAU,EACV,mBAAmB,GAGpB,MAAM,UAAU,CAAC"}