@atlanai/sdk 0.1.0

package/dist/resources.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The resource-oriented surface, built from the shipped resource map.
+ *
+ * Services are a deployment detail — they are base paths. Resources are what
+ * callers think in, so the client exposes resources rather than services:
+ * `client.sessions.messages.create(...)` instead of
+ * `client.agents.agentCreateSessionMessage({ sessionId, ... })`.
+ *
+ * The map is derived from the operation manifest and committed, so this module
+ * holds no naming rules of its own. Every call still lands on the generated
+ * method through its `Service`, which is what applies the request timeout, the
+ * workspace header, and error normalization.
+ */
+import type { Service } from "./client";
+interface ResourceMethod {
+    readonly operation_id: string;
+    /** The generated method each language's client answers to. */
+    readonly python: string;
+    readonly typescript: string;
+    /** The name this resource exposes, camelCased. */
+    readonly method_camel: string;
+    /**
+     * The options property holding the request body, when there is exactly one.
+     * Absent for multipart operations, which have no single body to unwrap.
+     */
+    readonly typescript_body?: string;
+    readonly route: string;
+    readonly summary: string;
+}
+interface ResourceEntry {
+    readonly service: string;
+    /** The resource's dotted path in TypeScript's convention. */
+    readonly typescript: string;
+    readonly methods: Readonly<Record<string, ResourceMethod>>;
+}
+interface ResourceDocument {
+    readonly schema_version: number;
+    readonly accessors: Readonly<Record<string, string>>;
+    readonly resources: Readonly<Record<string, ResourceEntry>>;
+}
+export declare const resourceMap: ResourceDocument;
+/** An operation reached as a resource method. Arguments pass through unchanged. */
+export type ResourceOperation = (...args: never[]) => Promise<unknown>;
+/**
+ * A resource: its own operations, plus any resources nested under it.
+ *
+ * Operations and children are resolved from the map at construction, so they
+ * are real own-properties rather than a Proxy — `Object.keys` and editor
+ * completion both see the actual surface.
+ */
+export interface Resource {
+    /** This resource's dotted path, e.g. `sessions.messages`. */
+    readonly name: string;
+    /** Method names, mapped to the generated method each one calls. */
+    readonly operations: Readonly<Record<string, string>>;
+    readonly [member: string]: ResourceOperation | Resource | string | Readonly<Record<string, string>>;
+}
+/**
+ * Build the top-level resources, nesting children under their parents.
+ *
+ * Resource keys are dotted paths (`agents.traces`), so the deepest are built
+ * first and handed to their parent.
+ */
+export declare function buildResources(document: ResourceDocument, services: Readonly<Record<string, Service>>): Record<string, Resource>;
+export {};

package/dist/resources.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * The resource-oriented surface, built from the shipped resource map.
+ *
+ * Services are a deployment detail — they are base paths. Resources are what
+ * callers think in, so the client exposes resources rather than services:
+ * `client.sessions.messages.create(...)` instead of
+ * `client.agents.agentCreateSessionMessage({ sessionId, ... })`.
+ *
+ * The map is derived from the operation manifest and committed, so this module
+ * holds no naming rules of its own. Every call still lands on the generated
+ * method through its `Service`, which is what applies the request timeout, the
+ * workspace header, and error normalization.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resourceMap = void 0;
+exports.buildResources = buildResources;
+const resources_json_1 = __importDefault(require("./resources.json"));
+const SCHEMA_VERSION = 1;
+exports.resourceMap = resources_json_1.default;
+if (exports.resourceMap.schema_version !== SCHEMA_VERSION) {
+    throw new Error(`resources.json declares schema_version ${exports.resourceMap.schema_version}; ` +
+        `this build understands ${SCHEMA_VERSION}`);
+}
+function camelCase(text) {
+    const [head, ...rest] = text.replace(/-/g, "_").split("_");
+    return head + rest.map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof Blob) &&
+        !(value instanceof Date));
+}
+/**
+ * Let a resource method be called the way Python's is.
+ *
+ * The generated clients take one options object, so the body sits under a
+ * property that repeats the model — `create({createWorkspaceBody: {...}})`.
+ * That name is exactly as unguessable as Python's keyword was, and path
+ * parameters have to be named too. So arguments may be passed positionally in
+ * route order with the body last: `update(agentId, {...})`, `create({...})`.
+ *
+ * The explicit options object still works, and is detected rather than
+ * guessed: a lone object argument carrying any of the expected property names
+ * is passed straight through.
+ */
+function positionalCall(forwarded, detail) {
+    const bodyKey = detail.typescript_body;
+    const pathKeys = [...detail.route.matchAll(/\{(\w+)\}/g)].map((match) => camelCase(match[1]));
+    // Path parameters need mapping even with no body. Gating this on the body
+    // alone let `get(agentId)` pass a bare string where the generated client
+    // wanted an object: no error, and the wrong resource fetched.
+    if (bodyKey === undefined && pathKeys.length === 0)
+        return forwarded;
+    const arity = pathKeys.length + (bodyKey === undefined ? 0 : 1);
+    const expected = new Set(bodyKey === undefined ? pathKeys : [...pathKeys, bodyKey]);
+    return ((...args) => {
+        const values = args;
+        if (values.length === 1 && isPlainObject(values[0])) {
+            const keys = Object.keys(values[0]);
+            if (keys.some((key) => expected.has(key))) {
+                return forwarded(...values);
+            }
+        }
+        if (values.length !== arity) {
+            // Not a shape this can map; let the generated client report it.
+            return forwarded(...values);
+        }
+        const options = {};
+        pathKeys.forEach((key, index) => {
+            options[key] = values[index];
+        });
+        if (bodyKey !== undefined)
+            options[bodyKey] = values[pathKeys.length];
+        return forwarded(options);
+    });
+}
+function buildResource(path, entry, service, children) {
+    const operations = {};
+    const resource = {
+        name: path,
+        operations,
+    };
+    for (const [method, detail] of Object.entries(entry.methods)) {
+        operations[detail.method_camel] = detail.typescript;
+        // Through the service, not the generated API: that is where the timeout,
+        // the workspace header and error normalization are applied.
+        const forwarded = service[detail.typescript];
+        if (typeof forwarded !== "function") {
+            throw new Error(`resource map names ${detail.typescript}, which the client does not expose`);
+        }
+        resource[detail.method_camel] = positionalCall(forwarded, detail);
+    }
+    for (const [name, child] of Object.entries(children)) {
+        if (name in resource) {
+            throw new Error(`resource '${path}' has both an operation and a child named '${name}'`);
+        }
+        resource[name] = child;
+    }
+    return Object.freeze(resource);
+}
+/**
+ * Build the top-level resources, nesting children under their parents.
+ *
+ * Resource keys are dotted paths (`agents.traces`), so the deepest are built
+ * first and handed to their parent.
+ */
+function buildResources(document, services) {
+    const pending = {};
+    const keys = Object.keys(document.resources).sort((left, right) => right.split(".").length - left.split(".").length);
+    for (const key of keys) {
+        const entry = document.resources[key];
+        const service = services[entry.service];
+        if (service === undefined) {
+            throw new Error(`resource map names service '${entry.service}', which is not built`);
+        }
+        const path = entry.typescript;
+        const resource = buildResource(path, entry, service, pending[key] ?? {});
+        delete pending[key];
+        const cut = key.lastIndexOf(".");
+        const parent = cut === -1 ? "" : key.slice(0, cut);
+        const leafKey = cut === -1 ? key : key.slice(cut + 1);
+        const leaf = camelCase(leafKey);
+        (pending[parent] ??= {})[leaf] = resource;
+    }
+    const top = pending[""] ?? {};
+    delete pending[""];
+    const orphans = Object.keys(pending);
+    if (orphans.length > 0) {
+        // A nested resource whose parent has no operations of its own would be
+        // unreachable, which is a map defect rather than something to paper over.
+        throw new Error(`resource map has orphaned children: ${orphans.sort().join(", ")}`);
+    }
+    return top;
+}