@elysra/tungsten-runtime 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,80 @@
+# @elysra/tungsten-runtime
+
+The TypeScript runtime for SDKs generated by [Tungsten](https://github.com/pboachie/tungsten), an OpenAPI compiler for agent-facing clients and tools.
+
+It provides HTTP transport, argument validation, retries, idempotency, structured error results, previews and confirmation, pagination, OAuth and server-sent events. The core package has no production dependencies.
+
+## Install
+
+```sh
+npm install @elysra/tungsten-runtime
+```
+
+The package uses ES modules and includes TypeScript declarations. Node.js 22 or newer is required on Node. The core entry point uses Web APIs; Node-specific filesystem adapters have their own export.
+
+## Use with a generated SDK
+
+Install the [Tungsten CLI](https://github.com/pboachie/tungsten#install), then initialize a project from your OpenAPI document:
+
+```sh
+tungsten init --from openapi.json --targets typescript
+tungsten check
+tungsten generate
+```
+
+Review `tungsten.yml` for the generated output directory and `agent.yml` for operation safety policies. Install and build the generated SDK in its output directory:
+
+```sh
+npm install
+npm run build
+```
+
+Generated clients already depend on this runtime. Use their typed resource methods for normal application code. To integrate at the descriptor level, import the generated descriptors and create a core:
+
+```ts
+import { ClientCore } from "@elysra/tungsten-runtime";
+import { api, operations } from "./generated/typescript/src/descriptors.js";
+
+const core = new ClientCore(api, {
+  baseUrl: "https://api.example.com",
+  operations,
+});
+
+// Select the operation your application intends to call.
+const operation = operations.find(op => op.id === "petstore.listPets");
+if (!operation) throw new Error("Operation not found in the generated API");
+
+const result = await core.call(operation, { limit: 10 });
+if (result.ok) {
+  console.log(result.value);
+} else {
+  console.error(result.error.category, result.error.remediation);
+}
+```
+
+Use the descriptor import path, operation ID and arguments generated for your own API. API and transport failures return a `Result` with a diagnostic envelope; they do not require parsing exception messages. `unwrap` and `throwing` are available for applications that prefer exceptions.
+
+## Safety and persistence
+
+Generated safety policies determine whether calls can retry, need idempotency keys, or require a preview and confirmation token. Confirmation tokens are bound to the arguments and client session that created them. Your API still enforces authentication and authorization.
+
+For Node applications that need idempotency keys to survive restarts:
+
+```ts
+import { FileIdempotencyStore } from "@elysra/tungsten-runtime/node";
+
+const idempotencyStore = new FileIdempotencyStore("./state/idempotency.json");
+// Pass idempotencyStore in the generated client's options or ClientCore options.
+```
+
+Keep `@elysra/tungsten-runtime/node` out of browser bundles. Applications own the storage location and its lifecycle.
+
+## Related packages and documentation
+
+- [@elysra/tungsten-mcp](https://www.npmjs.com/package/@elysra/tungsten-mcp): MCP servers for generated APIs.
+- [@elysra/tungsten-webmcp](https://www.npmjs.com/package/@elysra/tungsten-webmcp): browser WebMCP tool registration.
+- [Documentation](https://pboachie.github.io/tungsten/) and [source/issues](https://github.com/pboachie/tungsten).
+
+## License
+
+Apache-2.0. The Tungsten compiler is licensed separately under AGPL-3.0-only.

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 /** Version of `@elysra/tungsten-runtime`, sent in `X-Tungsten-Runtime`. Kept equal
  * to `package.json` `version`. */
-export declare const RUNTIME_VERSION = "0.1.0";
+export declare const RUNTIME_VERSION = "0.1.1";

package/dist/version.js

@@ -1,4 +1,4 @@
 // SPDX-License-Identifier: Apache-2.0
 /** Version of `@elysra/tungsten-runtime`, sent in `X-Tungsten-Runtime`. Kept equal
  * to `package.json` `version`. */
-export const RUNTIME_VERSION = "0.1.0";
+export const RUNTIME_VERSION = "0.1.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elysra/tungsten-runtime",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Runtime for SDKs generated by tungsten: transport, retries, idempotency, diagnostic error envelopes, previews and pagination.",
   "keywords": ["openapi", "sdk", "tungsten", "agents", "runtime", "typescript"],
   "homepage": "https://github.com/pboachie/tungsten",
@@ -17,7 +17,7 @@
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
     "./node": { "types": "./dist/node.d.ts", "import": "./dist/node.js" }
   },
-  "files": ["dist", "LICENSE"],
+  "files": ["dist", "LICENSE", "README.md"],
   "engines": { "node": ">=22" },
   "scripts": {
     "build": "tsc -p tsconfig.json"