@telnyx/edge-runtime 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+# `@telnyx/edge-runtime`
+
+Runtime SDK for Telnyx Edge Compute.

package/dist/build-env.d.ts

@@ -0,0 +1,51 @@
+import type { Env } from "./env.js";
+interface RuntimeBindingEntry {
+    binding: string;
+    type: "telnyx" | "secrets" | "actor";
+    actor_type?: string;
+    secret_name?: string;
+}
+/**
+ * Reads secrets declared in your `[[secrets]]` blocks.
+ *
+ * `handle` is the `binding` field — e.g. `env.SECRETS.get("GREETING")`.
+ * Throws `SecretsNotConfiguredError` when no `[[secrets]]` were declared,
+ * `SecretsError` for any other failure.
+ */
+export interface Secrets {
+    get(handle: string): Promise<string>;
+}
+export declare class SecretsError extends Error {
+    constructor(message: string);
+}
+export declare class SecretsNotConfiguredError extends SecretsError {
+    constructor(message: string);
+}
+/**
+ * Build the `env` object from the runtime-stamped environment variables.
+ *
+ * Returns an env with:
+ *   - `env.<telnyx-binding>` — pre-configured Telnyx client, attached
+ *     under the handle declared by `[telnyx] binding = "..."`.
+ *   - `env.SECRETS` — `.get(handle)` reads a secret declared in a
+ *     `[[secrets]]` block.
+ *
+ * Missing or malformed config yields an empty env rather than throwing,
+ * so module load can't crash on a misconfigured deploy. Calls to absent
+ * bindings fail at the call site with a standard `undefined`-access error.
+ */
+export declare function buildEnv(): Env;
+declare function loadRuntimeBindings(): RuntimeBindingEntry[];
+declare function resolveSecretsBindingName(): string;
+export declare const env: Env;
+/** Test seam. Not part of the public API. */
+export declare const __internal: {
+    DEFAULT_TELNYX_BASE_URL: string;
+    TELNYX_API_VERSION_PREFIX: string;
+    DEFAULT_DAPR_HTTP_PORT: string;
+    PLACEHOLDER_API_KEY: string;
+    loadRuntimeBindings: typeof loadRuntimeBindings;
+    resolveSecretsBindingName: typeof resolveSecretsBindingName;
+};
+export {};
+//# sourceMappingURL=build-env.d.ts.map

package/dist/build-env.js

@@ -0,0 +1,207 @@
+// Constructs the `env` object you use in your handler:
+//
+//     import { env } from "@telnyx/edge-runtime";
+//
+//     export default {
+//       async fetch(req: Request): Promise<Response> {
+//         const balance = await env.TELNYX_CLIENT.balance.retrieve();
+//         const greeting = await env.SECRETS.get("GREETING");
+//         // ...
+//       },
+//     };
+//
+// `buildEnv()` is also exported for tests that need to construct an env
+// with overridden process.env values.
+import Telnyx from "telnyx";
+const DEFAULT_TELNYX_BASE_URL = "http://localhost:3601";
+const TELNYX_API_VERSION_PREFIX = "/v2";
+const DEFAULT_DAPR_HTTP_PORT = "3500";
+// Non-empty placeholder so the Telnyx client attaches an Authorization
+// header. The real bearer is injected by the runtime before the request
+// leaves the pod; your code never holds an API key.
+const PLACEHOLDER_API_KEY = "auth-proxy-will-replace-this";
+export class SecretsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SecretsError";
+    }
+}
+export class SecretsNotConfiguredError extends SecretsError {
+    constructor(message) {
+        super(message);
+        this.name = "SecretsNotConfiguredError";
+    }
+}
+class SecretsImpl {
+    daprUrlRoot;
+    bindingName;
+    handleToSecretName;
+    constructor(daprUrlRoot, bindingName, handleToSecretName) {
+        this.daprUrlRoot = daprUrlRoot;
+        this.bindingName = bindingName;
+        this.handleToSecretName = handleToSecretName;
+    }
+    async get(handle) {
+        if (!this.bindingName) {
+            throw new SecretsNotConfiguredError("env.SECRETS.get(...) requires at least one [[secrets]] block in telnyx.toml.");
+        }
+        // Fall back to the handle itself if it wasn't declared with an
+        // explicit `name`, so [[secrets]] binding="FOO" (no name) works.
+        const secretName = this.handleToSecretName.get(handle) ?? handle;
+        const url = `${this.daprUrlRoot.replace(/\/+$/, "")}/v1.0/bindings/${this.bindingName}`;
+        let resp;
+        try {
+            resp = await fetch(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    operation: "get",
+                    metadata: { path: `/secrets/${secretName}` },
+                }),
+            });
+        }
+        catch (e) {
+            throw new SecretsError(`env.SECRETS.get(${JSON.stringify(handle)}) failed: ${e.message}`);
+        }
+        if (!resp.ok) {
+            const detail = await safeReadText(resp);
+            throw new SecretsError(`env.SECRETS.get(${JSON.stringify(handle)}) failed: HTTP ${resp.status}: ${detail}`);
+        }
+        let parsed;
+        try {
+            parsed = await resp.json();
+        }
+        catch (e) {
+            throw new SecretsError(`env.SECRETS.get(${JSON.stringify(handle)}) failed: response is not JSON: ${e.message}`);
+        }
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            !("value" in parsed) ||
+            typeof parsed.value !== "string") {
+            throw new SecretsError(`env.SECRETS.get(${JSON.stringify(handle)}) failed: response missing 'value' string field`);
+        }
+        return parsed.value;
+    }
+}
+/**
+ * Build the `env` object from the runtime-stamped environment variables.
+ *
+ * Returns an env with:
+ *   - `env.<telnyx-binding>` — pre-configured Telnyx client, attached
+ *     under the handle declared by `[telnyx] binding = "..."`.
+ *   - `env.SECRETS` — `.get(handle)` reads a secret declared in a
+ *     `[[secrets]]` block.
+ *
+ * Missing or malformed config yields an empty env rather than throwing,
+ * so module load can't crash on a misconfigured deploy. Calls to absent
+ * bindings fail at the call site with a standard `undefined`-access error.
+ */
+export function buildEnv() {
+    const env = {};
+    const entries = loadRuntimeBindings();
+    const telnyxBaseUrl = (process.env.TELNYX_API_BASE_URL ?? DEFAULT_TELNYX_BASE_URL).replace(/\/+$/, "") +
+        TELNYX_API_VERSION_PREFIX;
+    const daprPort = process.env.DAPR_HTTP_PORT ?? DEFAULT_DAPR_HTTP_PORT;
+    const daprUrlRoot = `http://localhost:${daprPort}`;
+    // Materialise env.SECRETS whenever a [[secrets]] entry exists, regardless
+    // of whether each carries a secret_name. Entries without one fall through
+    // SecretsImpl.get's `?? handle` path, so the customer still gets a
+    // working .get() — and if everything's misconfigured, they get the typed
+    // SecretsNotConfiguredError instead of a raw TypeError on `env.SECRETS`.
+    const secretsHandleMap = new Map();
+    for (const e of entries) {
+        if (e.type === "secrets" && typeof e.secret_name === "string" && e.secret_name) {
+            secretsHandleMap.set(e.binding, e.secret_name);
+        }
+    }
+    if (entries.some((e) => e.type === "secrets")) {
+        env.SECRETS = new SecretsImpl(daprUrlRoot, resolveSecretsBindingName(), secretsHandleMap);
+    }
+    // One Telnyx client is shared across every [telnyx] handle. The loop
+    // shape tolerates a future array-of-tables without a code change.
+    let telnyxClient = null;
+    for (const e of entries) {
+        if (e.type !== "telnyx")
+            continue;
+        if (telnyxClient === null) {
+            telnyxClient = new Telnyx({
+                apiKey: PLACEHOLDER_API_KEY,
+                baseURL: telnyxBaseUrl,
+            });
+        }
+        env[e.binding] = telnyxClient;
+    }
+    return env;
+}
+// ── helpers ──
+function loadRuntimeBindings() {
+    const raw = process.env.TELNYX_RUNTIME_BINDINGS ?? "";
+    if (!raw)
+        return [];
+    let decoded;
+    try {
+        decoded = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(decoded))
+        return [];
+    const out = [];
+    for (const item of decoded) {
+        if (typeof item === "object" &&
+            item !== null &&
+            typeof item.binding === "string" &&
+            item.binding !== "" &&
+            typeof item.type === "string") {
+            out.push(item);
+        }
+    }
+    return out;
+}
+// Explicit TELNYX_SECRETS_BINDING wins; otherwise derive from K_SERVICE;
+// otherwise return "" and env.SECRETS.get() throws SecretsNotConfiguredError.
+function resolveSecretsBindingName() {
+    const explicit = process.env.TELNYX_SECRETS_BINDING ?? "";
+    if (explicit)
+        return explicit;
+    const kService = process.env.K_SERVICE ?? "";
+    if (kService)
+        return `telnyx-secrets-${kService}`;
+    return "";
+}
+async function safeReadText(resp) {
+    try {
+        return (await resp.text()).slice(0, 200);
+    }
+    catch {
+        return "<unreadable>";
+    }
+}
+/**
+ * The `env` your handler uses. Built lazily on first access:
+ *
+ *     import { env } from "@telnyx/edge-runtime";
+ *
+ * Lazy so a plain `import` doesn't pay the cost — the work is small but
+ * non-zero, and consumers that import the package without touching `env`
+ * (e.g. type-only imports, other workspaces) shouldn't trigger it.
+ */
+let _env;
+const realEnv = () => (_env ??= buildEnv());
+export const env = new Proxy({}, {
+    get: (_, prop) => realEnv()[prop],
+    has: (_, prop) => prop in realEnv(),
+    ownKeys: () => Reflect.ownKeys(realEnv()),
+    getOwnPropertyDescriptor: (_, prop) => Reflect.getOwnPropertyDescriptor(realEnv(), prop),
+});
+/** Test seam. Not part of the public API. */
+export const __internal = {
+    DEFAULT_TELNYX_BASE_URL,
+    TELNYX_API_VERSION_PREFIX,
+    DEFAULT_DAPR_HTTP_PORT,
+    PLACEHOLDER_API_KEY,
+    loadRuntimeBindings,
+    resolveSecretsBindingName,
+};
+//# sourceMappingURL=build-env.js.map

package/dist/env.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Customer-extensible bindings environment.
+ *
+ * Customers either pass their own typed env (`StatefulActor<MyEnv>`) or rely on
+ * codegen to augment the global `Env` interface.
+ */
+export interface Env {
+    [binding: string]: unknown;
+}
+//# sourceMappingURL=env.d.ts.map

package/dist/env.js

@@ -0,0 +1,11 @@
+// Customers extend this via the codegen produced by `telnyx types`. Given:
+//
+//   [[actors]]
+//   binding = "COUNTER"
+//   type    = "Counter"
+//
+// `env.COUNTER` becomes typed as a stub against `Counter`'s public method
+// shape. The base type below is intentionally loose so `class MyActor
+// extends StatefulActor<Env>` typechecks before codegen runs.
+export {};
+//# sourceMappingURL=env.js.map

package/dist/public.d.ts

@@ -0,0 +1,4 @@
+export type { Env } from "./env.js";
+export { env, buildEnv, SecretsError, SecretsNotConfiguredError } from "./build-env.js";
+export type { Secrets } from "./build-env.js";
+//# sourceMappingURL=public.d.ts.map

package/dist/public.js

@@ -0,0 +1,11 @@
+// `@telnyx/edge-runtime` — public customer-facing entry.
+//
+// V0 scope: only the `env` surface is published. The rest of the SDK
+// (StatefulActor, ActorContext, ActorStorage, ActorNamespace, the typed
+// actor errors) lives in src/ and is exported from ./index.ts for
+// in-monorepo consumers, but is held back from the npm tarball until the
+// actor path is reachable end-to-end. Re-adding any of those for customers
+// is a single-line re-export here.
+// `env` — the bindings declared in telnyx.toml, ready to use in your handler.
+export { env, buildEnv, SecretsError, SecretsNotConfiguredError } from "./build-env.js";
+//# sourceMappingURL=public.js.map

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@telnyx/edge-runtime",
+  "private": false,
+  "version": "0.1.0",
+  "description": "Telnyx Edge Compute - Runtime SDK",
+  "type": "module",
+  "main": "./dist/public.js",
+  "types": "./dist/public.d.ts",
+  "files": [
+    "dist/public.js",
+    "dist/public.d.ts",
+    "dist/build-env.js",
+    "dist/build-env.d.ts",
+    "dist/env.js",
+    "dist/env.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.lint.json"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/public.d.ts",
+      "import": "./dist/public.js"
+    },
+    "./internal": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "telnyx": "*",
+    "ws": "*"
+  }
+}