@glytos/node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Glytos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# @glytos/node
+
+[![CI](https://github.com/Glytos/glytos-sdk-node/actions/workflows/ci.yml/badge.svg)](https://github.com/Glytos/glytos-sdk-node/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@glytos/node)](https://www.npmjs.com/package/@glytos/node)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+The official [Glytos](https://glytos.com) server SDK for Node.js and TypeScript.
+
+Call the Glytos API from your backend with an API key: build and run voice agents,
+start phone calls, mint browser web-call tokens, manage phone numbers, and verify
+webhooks. Zero dependencies, fully typed, ESM.
+
+> Never ship an API key to the browser. For in-browser voice, use
+> [`@glytos/web`](https://www.npmjs.com/package/@glytos/web) with a short-lived
+> token you mint here.
+
+## Install
+
+```bash
+npm install @glytos/node
+```
+
+Requires Node.js 18+ (uses the global `fetch`).
+
+## Quickstart
+
+```ts
+import { Glytos } from '@glytos/node';
+
+const glytos = new Glytos(process.env.GLYTOS_API_KEY!);
+
+// List your agents
+const agents = await glytos.workflows.list();
+
+// Mint a web-call token for the browser
+const { token, ws_url } = await glytos.calls.webToken({
+  workflow_uuid: agents[0].uuid,
+});
+```
+
+The base URL defaults to the public API. Override it for a regional stack:
+
+```ts
+const glytos = new Glytos({ apiKey: '...', baseUrl: 'https://api.glytos.com/api/v1' });
+```
+
+## Resources
+
+| Namespace | Methods |
+| --- | --- |
+| `glytos.workflows` | `list`, `retrieve`, `create`, `publish`, `delete`, `templates`, `session`, `sessionEvents` |
+| `glytos.calls` | `create`, `list`, `retrieve`, `webToken`, `control` |
+| `glytos.phoneNumbers` | `search`, `list`, `provision`, `assign`, `release` |
+| `glytos.sessions` | `list` |
+| `glytos.webhooks` | `list`, `create`, `delete`, `events`, `verify` |
+
+Any endpoint without a dedicated helper is one call away:
+
+```ts
+const overview = await glytos.request('GET', '/analytics/overview');
+```
+
+## Errors
+
+Non-2xx responses throw a `GlytosError` with the API error `code`, HTTP `status`,
+and the `requestId` for support:
+
+```ts
+import { GlytosError } from '@glytos/node';
+
+try {
+  await glytos.workflows.retrieve('missing');
+} catch (err) {
+  if (err instanceof GlytosError) {
+    console.error(err.status, err.code, err.message);
+  }
+}
+```
+
+## Webhooks
+
+Verify that a delivery really came from Glytos before trusting it. Pass the **raw**
+request body, the `X-Glytos-Signature` header, and your endpoint secret:
+
+```ts
+app.post('/webhooks/glytos', express.raw({ type: 'application/json' }), (req, res) => {
+  const ok = glytos.webhooks.verify(
+    req.body, // raw Buffer
+    req.header('X-Glytos-Signature') ?? '',
+    process.env.GLYTOS_WEBHOOK_SECRET!,
+  );
+  if (!ok) return res.status(400).end();
+  const event = JSON.parse(req.body.toString());
+  // handle event...
+  res.status(200).end();
+});
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,196 @@
+/**
+ * @glytos/node - the official Glytos server SDK for Node.js and TypeScript.
+ *
+ * Use it from your backend with an API key. Never ship an API key to the browser;
+ * for in-browser voice use `@glytos/web` with a short-lived, workflow-scoped token
+ * you mint here via `calls.webToken(...)`.
+ *
+ * ```ts
+ * import { Glytos } from '@glytos/node';
+ *
+ * const glytos = new Glytos(process.env.GLYTOS_API_KEY!);
+ *
+ * const agents = await glytos.workflows.list();
+ * const { token, ws_url } = await glytos.calls.webToken({ workflow_uuid: agents[0].uuid });
+ * ```
+ *
+ * Every resource method is a thin, typed wrapper over the REST API. For endpoints
+ * without a dedicated helper, call `glytos.request(method, path, { body, query })`.
+ */
+export interface GlytosOptions {
+    /** Your organization API key (starts with `gly_`). */
+    apiKey: string;
+    /** Override the API base URL (e.g. a regional stack). Defaults to the public API. */
+    baseUrl?: string;
+    /**
+     * The environment to act in: `"dev"`, `"staging"`, `"prod"`, or an environment
+     * uuid. Defaults to the organization's default environment (Development). Agents
+     * are still created in Development regardless of this; it scopes reads and calls.
+     */
+    environment?: string;
+    /** Custom fetch implementation. Defaults to the global `fetch` (Node 18+). */
+    fetch?: typeof fetch;
+}
+/** Thrown on any non-2xx API response. Carries the API error `code` and status. */
+export declare class GlytosError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string | undefined;
+    constructor(status: number, code: string, message: string, requestId?: string);
+}
+type Primitive = string | number | boolean;
+export type Query = Record<string, Primitive | undefined | null>;
+export interface RequestOptions {
+    query?: Query;
+    body?: unknown;
+}
+export interface Workflow {
+    uuid: string;
+    name: string;
+    mode: string;
+    status?: string;
+    archived?: boolean;
+    [key: string]: unknown;
+}
+export interface Call {
+    uuid: string;
+    status: string;
+    [key: string]: unknown;
+}
+export interface WebCallToken {
+    token: string;
+    ws_url: string;
+    [key: string]: unknown;
+}
+export interface PhoneNumber {
+    uuid: string;
+    e164: string;
+    [key: string]: unknown;
+}
+export interface Session {
+    session_uuid: string;
+    workflow_uuid?: string;
+    mode?: string;
+    status: string;
+    created_at?: string;
+    [key: string]: unknown;
+}
+export interface WebhookEndpoint {
+    id: number;
+    url: string;
+    events: string[];
+    [key: string]: unknown;
+}
+declare class Workflows {
+    private readonly client;
+    constructor(client: Glytos);
+    /** List your agents (prompt agents and visual workflows). */
+    list(): Promise<Workflow[]>;
+    /** Retrieve a single agent by uuid. */
+    retrieve(workflowUuid: string): Promise<Workflow>;
+    /** Create an agent. `mode` is `"prompt"` (default) or `"workflow"`. */
+    create(body: {
+        name: string;
+        mode?: 'prompt' | 'workflow';
+        config?: Record<string, unknown>;
+    }): Promise<Workflow>;
+    /** Publish the current draft so the agent goes live. */
+    publish(workflowUuid: string): Promise<Workflow>;
+    /** Delete an agent. */
+    delete(workflowUuid: string): Promise<void>;
+    /** Ready-made starter workflow graphs. */
+    templates(): Promise<Workflow[]>;
+    /** Full detail for one session of an agent (transcript, cost, latency, ...). */
+    session(workflowUuid: string, sessionUuid: string): Promise<Session>;
+    /** The run-event log for a session (routing decisions, tool calls, ...). */
+    sessionEvents(workflowUuid: string, sessionUuid: string): Promise<unknown[]>;
+}
+declare class Calls {
+    private readonly client;
+    constructor(client: Glytos);
+    /** Start an outbound phone call, or run a transient agent. */
+    create(body: Record<string, unknown>): Promise<Call>;
+    /** List calls. */
+    list(query?: Query): Promise<Call[]>;
+    /** Retrieve a call by uuid. */
+    retrieve(callUuid: string): Promise<Call>;
+    /**
+     * Mint a short-lived, workflow-scoped token for an in-browser web call. Hand the
+     * returned `{ token, ws_url }` to the browser and connect with `@glytos/web`.
+     */
+    webToken(body: {
+        workflow_uuid?: string;
+        agent?: Record<string, unknown>;
+    }): Promise<WebCallToken>;
+    /** Control an in-progress call (e.g. transfer, hang up). */
+    control(callUuid: string, body: Record<string, unknown>): Promise<unknown>;
+}
+declare class PhoneNumbers {
+    private readonly client;
+    constructor(client: Glytos);
+    /** Search carrier inventory for available numbers. */
+    search(query: Query): Promise<unknown[]>;
+    /** List the numbers on your account. */
+    list(): Promise<PhoneNumber[]>;
+    /** Provision (buy) a number by its e164 value. */
+    provision(body: {
+        e164: string;
+        [key: string]: unknown;
+    }): Promise<PhoneNumber>;
+    /** Assign a number to an agent. */
+    assign(numberUuid: string, body: Record<string, unknown>): Promise<PhoneNumber>;
+    /** Release (delete) a number. */
+    release(numberUuid: string): Promise<void>;
+}
+declare class Sessions {
+    private readonly client;
+    constructor(client: Glytos);
+    /** List sessions across your agents. */
+    list(query?: Query): Promise<Session[]>;
+}
+declare class Webhooks {
+    private readonly client;
+    constructor(client: Glytos);
+    /** List your webhook endpoints. */
+    list(): Promise<WebhookEndpoint[]>;
+    /** Create a webhook endpoint subscribed to the given events. */
+    create(body: {
+        url: string;
+        events: string[];
+        [key: string]: unknown;
+    }): Promise<WebhookEndpoint>;
+    /** Delete a webhook endpoint. */
+    delete(endpointId: number | string): Promise<void>;
+    /** The catalog of webhook event types you can subscribe to. */
+    events(): Promise<unknown[]>;
+    /**
+     * Verify a webhook delivery signature. Pass the RAW request body (string or
+     * Buffer), the `X-Glytos-Signature` header value, and the endpoint secret.
+     * Returns true only if the signature is valid and within the tolerance window.
+     */
+    verify(payload: string | Buffer, signatureHeader: string, secret: string, toleranceSeconds?: number): boolean;
+}
+export declare class Glytos {
+    readonly workflows: Workflows;
+    readonly calls: Calls;
+    readonly phoneNumbers: PhoneNumbers;
+    readonly sessions: Sessions;
+    readonly webhooks: Webhooks;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly environment?;
+    private readonly fetchImpl;
+    constructor(options: GlytosOptions | string);
+    /**
+     * Low-level request against any API endpoint. Path is relative to the API base
+     * (e.g. `"/workflows"`). Throws `GlytosError` on a non-2xx response.
+     */
+    request<T = unknown>(method: string, path: string, options?: RequestOptions): Promise<T>;
+}
+/**
+ * Standalone webhook signature verifier (also available as `glytos.webhooks.verify`).
+ * Matches the server scheme: HMAC-SHA256 over `"{timestamp}.{body}"`, sent as
+ * `X-Glytos-Signature: t=<ts>,v1=<hex>`.
+ */
+export declare function verifyWebhook(payload: string | Buffer, signatureHeader: string, secret: string, toleranceSeconds?: number): boolean;
+export default Glytos;

package/dist/index.js

@@ -0,0 +1,256 @@
+/**
+ * @glytos/node - the official Glytos server SDK for Node.js and TypeScript.
+ *
+ * Use it from your backend with an API key. Never ship an API key to the browser;
+ * for in-browser voice use `@glytos/web` with a short-lived, workflow-scoped token
+ * you mint here via `calls.webToken(...)`.
+ *
+ * ```ts
+ * import { Glytos } from '@glytos/node';
+ *
+ * const glytos = new Glytos(process.env.GLYTOS_API_KEY!);
+ *
+ * const agents = await glytos.workflows.list();
+ * const { token, ws_url } = await glytos.calls.webToken({ workflow_uuid: agents[0].uuid });
+ * ```
+ *
+ * Every resource method is a thin, typed wrapper over the REST API. For endpoints
+ * without a dedicated helper, call `glytos.request(method, path, { body, query })`.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+const DEFAULT_BASE_URL = 'https://api.glytos.com/api/v1';
+/** Thrown on any non-2xx API response. Carries the API error `code` and status. */
+export class GlytosError extends Error {
+    constructor(status, code, message, requestId) {
+        super(message);
+        this.name = 'GlytosError';
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+    }
+}
+const enc = encodeURIComponent;
+class Workflows {
+    constructor(client) {
+        this.client = client;
+    }
+    /** List your agents (prompt agents and visual workflows). */
+    list() {
+        return this.client.request('GET', '/workflows');
+    }
+    /** Retrieve a single agent by uuid. */
+    retrieve(workflowUuid) {
+        return this.client.request('GET', `/workflows/${enc(workflowUuid)}`);
+    }
+    /** Create an agent. `mode` is `"prompt"` (default) or `"workflow"`. */
+    create(body) {
+        return this.client.request('POST', '/workflows', { body });
+    }
+    /** Publish the current draft so the agent goes live. */
+    publish(workflowUuid) {
+        return this.client.request('POST', `/workflows/${enc(workflowUuid)}/publish`);
+    }
+    /** Delete an agent. */
+    delete(workflowUuid) {
+        return this.client.request('DELETE', `/workflows/${enc(workflowUuid)}`);
+    }
+    /** Ready-made starter workflow graphs. */
+    templates() {
+        return this.client.request('GET', '/workflows/templates');
+    }
+    /** Full detail for one session of an agent (transcript, cost, latency, ...). */
+    session(workflowUuid, sessionUuid) {
+        return this.client.request('GET', `/workflows/${enc(workflowUuid)}/sessions/${enc(sessionUuid)}`);
+    }
+    /** The run-event log for a session (routing decisions, tool calls, ...). */
+    sessionEvents(workflowUuid, sessionUuid) {
+        return this.client.request('GET', `/workflows/${enc(workflowUuid)}/sessions/${enc(sessionUuid)}/events`);
+    }
+}
+class Calls {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Start an outbound phone call, or run a transient agent. */
+    create(body) {
+        return this.client.request('POST', '/calls', { body });
+    }
+    /** List calls. */
+    list(query) {
+        return this.client.request('GET', '/calls', { query });
+    }
+    /** Retrieve a call by uuid. */
+    retrieve(callUuid) {
+        return this.client.request('GET', `/calls/${enc(callUuid)}`);
+    }
+    /**
+     * Mint a short-lived, workflow-scoped token for an in-browser web call. Hand the
+     * returned `{ token, ws_url }` to the browser and connect with `@glytos/web`.
+     */
+    webToken(body) {
+        return this.client.request('POST', '/calls/web-token', { body });
+    }
+    /** Control an in-progress call (e.g. transfer, hang up). */
+    control(callUuid, body) {
+        return this.client.request('POST', `/calls/${enc(callUuid)}/control`, { body });
+    }
+}
+class PhoneNumbers {
+    constructor(client) {
+        this.client = client;
+    }
+    /** Search carrier inventory for available numbers. */
+    search(query) {
+        return this.client.request('GET', '/telephony/numbers/search', { query });
+    }
+    /** List the numbers on your account. */
+    list() {
+        return this.client.request('GET', '/telephony/numbers');
+    }
+    /** Provision (buy) a number by its e164 value. */
+    provision(body) {
+        return this.client.request('POST', '/telephony/numbers', { body });
+    }
+    /** Assign a number to an agent. */
+    assign(numberUuid, body) {
+        return this.client.request('POST', `/telephony/numbers/${enc(numberUuid)}/assign`, { body });
+    }
+    /** Release (delete) a number. */
+    release(numberUuid) {
+        return this.client.request('DELETE', `/telephony/numbers/${enc(numberUuid)}`);
+    }
+}
+class Sessions {
+    constructor(client) {
+        this.client = client;
+    }
+    /** List sessions across your agents. */
+    list(query) {
+        return this.client.request('GET', '/sessions', { query });
+    }
+}
+class Webhooks {
+    constructor(client) {
+        this.client = client;
+    }
+    /** List your webhook endpoints. */
+    list() {
+        return this.client.request('GET', '/webhooks/endpoints');
+    }
+    /** Create a webhook endpoint subscribed to the given events. */
+    create(body) {
+        return this.client.request('POST', '/webhooks/endpoints', { body });
+    }
+    /** Delete a webhook endpoint. */
+    delete(endpointId) {
+        return this.client.request('DELETE', `/webhooks/endpoints/${enc(String(endpointId))}`);
+    }
+    /** The catalog of webhook event types you can subscribe to. */
+    events() {
+        return this.client.request('GET', '/webhooks/events');
+    }
+    /**
+     * Verify a webhook delivery signature. Pass the RAW request body (string or
+     * Buffer), the `X-Glytos-Signature` header value, and the endpoint secret.
+     * Returns true only if the signature is valid and within the tolerance window.
+     */
+    verify(payload, signatureHeader, secret, toleranceSeconds = 300) {
+        return verifyWebhook(payload, signatureHeader, secret, toleranceSeconds);
+    }
+}
+export class Glytos {
+    constructor(options) {
+        const opts = typeof options === 'string' ? { apiKey: options } : options;
+        if (!opts.apiKey)
+            throw new Error('Glytos: an apiKey is required');
+        this.apiKey = opts.apiKey;
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.environment = opts.environment;
+        const fetchImpl = opts.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== 'function') {
+            throw new Error('Glytos: no global fetch found; upgrade to Node 18+ or pass options.fetch');
+        }
+        this.fetchImpl = fetchImpl;
+        this.workflows = new Workflows(this);
+        this.calls = new Calls(this);
+        this.phoneNumbers = new PhoneNumbers(this);
+        this.sessions = new Sessions(this);
+        this.webhooks = new Webhooks(this);
+    }
+    /**
+     * Low-level request against any API endpoint. Path is relative to the API base
+     * (e.g. `"/workflows"`). Throws `GlytosError` on a non-2xx response.
+     */
+    async request(method, path, options = {}) {
+        const url = new URL(this.baseUrl + path);
+        if (options.query) {
+            for (const [key, value] of Object.entries(options.query)) {
+                if (value !== undefined && value !== null)
+                    url.searchParams.set(key, String(value));
+            }
+        }
+        const headers = {
+            'X-API-Key': this.apiKey,
+            Accept: 'application/json',
+        };
+        if (this.environment)
+            headers['X-Environment-Id'] = this.environment;
+        const init = { method, headers };
+        if (options.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(options.body);
+        }
+        const response = await this.fetchImpl(url.toString(), init);
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        const text = await response.text();
+        const data = text ? safeParse(text) : undefined;
+        if (!response.ok) {
+            const error = data?.error;
+            throw new GlytosError(response.status, error?.code ?? 'error', error?.message ?? (response.statusText || 'Request failed'), requestId);
+        }
+        return data;
+    }
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * Standalone webhook signature verifier (also available as `glytos.webhooks.verify`).
+ * Matches the server scheme: HMAC-SHA256 over `"{timestamp}.{body}"`, sent as
+ * `X-Glytos-Signature: t=<ts>,v1=<hex>`.
+ */
+export function verifyWebhook(payload, signatureHeader, secret, toleranceSeconds = 300) {
+    const parts = {};
+    for (const piece of signatureHeader.split(',')) {
+        const idx = piece.indexOf('=');
+        if (idx > 0)
+            parts[piece.slice(0, idx).trim()] = piece.slice(idx + 1).trim();
+    }
+    const timestamp = parts['t'];
+    const provided = parts['v1'];
+    if (!timestamp || !provided)
+        return false;
+    const body = typeof payload === 'string' ? Buffer.from(payload, 'utf8') : payload;
+    const signed = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), body]);
+    const expected = createHmac('sha256', secret).update(signed).digest('hex');
+    const expectedBuf = Buffer.from(expected, 'utf8');
+    const providedBuf = Buffer.from(provided, 'utf8');
+    if (expectedBuf.length !== providedBuf.length)
+        return false;
+    if (!timingSafeEqual(expectedBuf, providedBuf))
+        return false;
+    if (toleranceSeconds > 0) {
+        const ts = Number.parseInt(timestamp, 10);
+        if (!Number.isFinite(ts))
+            return false;
+        if (Math.abs(Date.now() / 1000 - ts) > toleranceSeconds)
+            return false;
+    }
+    return true;
+}
+export default Glytos;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@glytos/node",
+  "version": "0.1.0",
+  "description": "Official Glytos server SDK for Node.js and TypeScript.",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "files": ["dist", "src", "README.md"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["glytos", "voice", "ai", "agent", "sdk", "api"],
+  "author": "Glytos",
+  "license": "MIT",
+  "homepage": "https://glytos.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Glytos/glytos-sdk-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Glytos/glytos-sdk-node/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,396 @@
+/**
+ * @glytos/node - the official Glytos server SDK for Node.js and TypeScript.
+ *
+ * Use it from your backend with an API key. Never ship an API key to the browser;
+ * for in-browser voice use `@glytos/web` with a short-lived, workflow-scoped token
+ * you mint here via `calls.webToken(...)`.
+ *
+ * ```ts
+ * import { Glytos } from '@glytos/node';
+ *
+ * const glytos = new Glytos(process.env.GLYTOS_API_KEY!);
+ *
+ * const agents = await glytos.workflows.list();
+ * const { token, ws_url } = await glytos.calls.webToken({ workflow_uuid: agents[0].uuid });
+ * ```
+ *
+ * Every resource method is a thin, typed wrapper over the REST API. For endpoints
+ * without a dedicated helper, call `glytos.request(method, path, { body, query })`.
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+const DEFAULT_BASE_URL = 'https://api.glytos.com/api/v1';
+
+export interface GlytosOptions {
+  /** Your organization API key (starts with `gly_`). */
+  apiKey: string;
+  /** Override the API base URL (e.g. a regional stack). Defaults to the public API. */
+  baseUrl?: string;
+  /**
+   * The environment to act in: `"dev"`, `"staging"`, `"prod"`, or an environment
+   * uuid. Defaults to the organization's default environment (Development). Agents
+   * are still created in Development regardless of this; it scopes reads and calls.
+   */
+  environment?: string;
+  /** Custom fetch implementation. Defaults to the global `fetch` (Node 18+). */
+  fetch?: typeof fetch;
+}
+
+/** Thrown on any non-2xx API response. Carries the API error `code` and status. */
+export class GlytosError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly requestId: string | undefined;
+
+  constructor(status: number, code: string, message: string, requestId?: string) {
+    super(message);
+    this.name = 'GlytosError';
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+  }
+}
+
+type Primitive = string | number | boolean;
+export type Query = Record<string, Primitive | undefined | null>;
+
+export interface RequestOptions {
+  query?: Query;
+  body?: unknown;
+}
+
+// Entity shapes carry the fields you rely on plus an index signature, so they stay
+// forward-compatible as the API grows (new fields never break your build).
+export interface Workflow {
+  uuid: string;
+  name: string;
+  mode: string;
+  status?: string;
+  archived?: boolean;
+  [key: string]: unknown;
+}
+
+export interface Call {
+  uuid: string;
+  status: string;
+  [key: string]: unknown;
+}
+
+export interface WebCallToken {
+  token: string;
+  ws_url: string;
+  [key: string]: unknown;
+}
+
+export interface PhoneNumber {
+  uuid: string;
+  e164: string;
+  [key: string]: unknown;
+}
+
+export interface Session {
+  session_uuid: string;
+  workflow_uuid?: string;
+  mode?: string;
+  status: string;
+  created_at?: string;
+  [key: string]: unknown;
+}
+
+export interface WebhookEndpoint {
+  id: number;
+  url: string;
+  events: string[];
+  [key: string]: unknown;
+}
+
+const enc = encodeURIComponent;
+
+class Workflows {
+  constructor(private readonly client: Glytos) {}
+
+  /** List your agents (prompt agents and visual workflows). */
+  list(): Promise<Workflow[]> {
+    return this.client.request('GET', '/workflows');
+  }
+
+  /** Retrieve a single agent by uuid. */
+  retrieve(workflowUuid: string): Promise<Workflow> {
+    return this.client.request('GET', `/workflows/${enc(workflowUuid)}`);
+  }
+
+  /** Create an agent. `mode` is `"prompt"` (default) or `"workflow"`. */
+  create(body: {
+    name: string;
+    mode?: 'prompt' | 'workflow';
+    config?: Record<string, unknown>;
+  }): Promise<Workflow> {
+    return this.client.request('POST', '/workflows', { body });
+  }
+
+  /** Publish the current draft so the agent goes live. */
+  publish(workflowUuid: string): Promise<Workflow> {
+    return this.client.request('POST', `/workflows/${enc(workflowUuid)}/publish`);
+  }
+
+  /** Delete an agent. */
+  delete(workflowUuid: string): Promise<void> {
+    return this.client.request('DELETE', `/workflows/${enc(workflowUuid)}`);
+  }
+
+  /** Ready-made starter workflow graphs. */
+  templates(): Promise<Workflow[]> {
+    return this.client.request('GET', '/workflows/templates');
+  }
+
+  /** Full detail for one session of an agent (transcript, cost, latency, ...). */
+  session(workflowUuid: string, sessionUuid: string): Promise<Session> {
+    return this.client.request(
+      'GET',
+      `/workflows/${enc(workflowUuid)}/sessions/${enc(sessionUuid)}`,
+    );
+  }
+
+  /** The run-event log for a session (routing decisions, tool calls, ...). */
+  sessionEvents(workflowUuid: string, sessionUuid: string): Promise<unknown[]> {
+    return this.client.request(
+      'GET',
+      `/workflows/${enc(workflowUuid)}/sessions/${enc(sessionUuid)}/events`,
+    );
+  }
+}
+
+class Calls {
+  constructor(private readonly client: Glytos) {}
+
+  /** Start an outbound phone call, or run a transient agent. */
+  create(body: Record<string, unknown>): Promise<Call> {
+    return this.client.request('POST', '/calls', { body });
+  }
+
+  /** List calls. */
+  list(query?: Query): Promise<Call[]> {
+    return this.client.request('GET', '/calls', { query });
+  }
+
+  /** Retrieve a call by uuid. */
+  retrieve(callUuid: string): Promise<Call> {
+    return this.client.request('GET', `/calls/${enc(callUuid)}`);
+  }
+
+  /**
+   * Mint a short-lived, workflow-scoped token for an in-browser web call. Hand the
+   * returned `{ token, ws_url }` to the browser and connect with `@glytos/web`.
+   */
+  webToken(body: {
+    workflow_uuid?: string;
+    agent?: Record<string, unknown>;
+  }): Promise<WebCallToken> {
+    return this.client.request('POST', '/calls/web-token', { body });
+  }
+
+  /** Control an in-progress call (e.g. transfer, hang up). */
+  control(callUuid: string, body: Record<string, unknown>): Promise<unknown> {
+    return this.client.request('POST', `/calls/${enc(callUuid)}/control`, { body });
+  }
+}
+
+class PhoneNumbers {
+  constructor(private readonly client: Glytos) {}
+
+  /** Search carrier inventory for available numbers. */
+  search(query: Query): Promise<unknown[]> {
+    return this.client.request('GET', '/telephony/numbers/search', { query });
+  }
+
+  /** List the numbers on your account. */
+  list(): Promise<PhoneNumber[]> {
+    return this.client.request('GET', '/telephony/numbers');
+  }
+
+  /** Provision (buy) a number by its e164 value. */
+  provision(body: { e164: string; [key: string]: unknown }): Promise<PhoneNumber> {
+    return this.client.request('POST', '/telephony/numbers', { body });
+  }
+
+  /** Assign a number to an agent. */
+  assign(numberUuid: string, body: Record<string, unknown>): Promise<PhoneNumber> {
+    return this.client.request('POST', `/telephony/numbers/${enc(numberUuid)}/assign`, { body });
+  }
+
+  /** Release (delete) a number. */
+  release(numberUuid: string): Promise<void> {
+    return this.client.request('DELETE', `/telephony/numbers/${enc(numberUuid)}`);
+  }
+}
+
+class Sessions {
+  constructor(private readonly client: Glytos) {}
+
+  /** List sessions across your agents. */
+  list(query?: Query): Promise<Session[]> {
+    return this.client.request('GET', '/sessions', { query });
+  }
+}
+
+class Webhooks {
+  constructor(private readonly client: Glytos) {}
+
+  /** List your webhook endpoints. */
+  list(): Promise<WebhookEndpoint[]> {
+    return this.client.request('GET', '/webhooks/endpoints');
+  }
+
+  /** Create a webhook endpoint subscribed to the given events. */
+  create(body: { url: string; events: string[]; [key: string]: unknown }): Promise<WebhookEndpoint> {
+    return this.client.request('POST', '/webhooks/endpoints', { body });
+  }
+
+  /** Delete a webhook endpoint. */
+  delete(endpointId: number | string): Promise<void> {
+    return this.client.request('DELETE', `/webhooks/endpoints/${enc(String(endpointId))}`);
+  }
+
+  /** The catalog of webhook event types you can subscribe to. */
+  events(): Promise<unknown[]> {
+    return this.client.request('GET', '/webhooks/events');
+  }
+
+  /**
+   * Verify a webhook delivery signature. Pass the RAW request body (string or
+   * Buffer), the `X-Glytos-Signature` header value, and the endpoint secret.
+   * Returns true only if the signature is valid and within the tolerance window.
+   */
+  verify(
+    payload: string | Buffer,
+    signatureHeader: string,
+    secret: string,
+    toleranceSeconds = 300,
+  ): boolean {
+    return verifyWebhook(payload, signatureHeader, secret, toleranceSeconds);
+  }
+}
+
+export class Glytos {
+  readonly workflows: Workflows;
+  readonly calls: Calls;
+  readonly phoneNumbers: PhoneNumbers;
+  readonly sessions: Sessions;
+  readonly webhooks: Webhooks;
+
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly environment?: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: GlytosOptions | string) {
+    const opts: GlytosOptions = typeof options === 'string' ? { apiKey: options } : options;
+    if (!opts.apiKey) throw new Error('Glytos: an apiKey is required');
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    this.environment = opts.environment;
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+      throw new Error('Glytos: no global fetch found; upgrade to Node 18+ or pass options.fetch');
+    }
+    this.fetchImpl = fetchImpl;
+
+    this.workflows = new Workflows(this);
+    this.calls = new Calls(this);
+    this.phoneNumbers = new PhoneNumbers(this);
+    this.sessions = new Sessions(this);
+    this.webhooks = new Webhooks(this);
+  }
+
+  /**
+   * Low-level request against any API endpoint. Path is relative to the API base
+   * (e.g. `"/workflows"`). Throws `GlytosError` on a non-2xx response.
+   */
+  async request<T = unknown>(
+    method: string,
+    path: string,
+    options: RequestOptions = {},
+  ): Promise<T> {
+    const url = new URL(this.baseUrl + path);
+    if (options.query) {
+      for (const [key, value] of Object.entries(options.query)) {
+        if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
+      }
+    }
+
+    const headers: Record<string, string> = {
+      'X-API-Key': this.apiKey,
+      Accept: 'application/json',
+    };
+    if (this.environment) headers['X-Environment-Id'] = this.environment;
+    const init: RequestInit = { method, headers };
+    if (options.body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+      init.body = JSON.stringify(options.body);
+    }
+
+    const response = await this.fetchImpl(url.toString(), init);
+    const requestId = response.headers.get('x-request-id') ?? undefined;
+    const text = await response.text();
+    const data = text ? safeParse(text) : undefined;
+
+    if (!response.ok) {
+      const error = (data as { error?: { code?: string; message?: string } } | undefined)?.error;
+      throw new GlytosError(
+        response.status,
+        error?.code ?? 'error',
+        error?.message ?? (response.statusText || 'Request failed'),
+        requestId,
+      );
+    }
+    return data as T;
+  }
+}
+
+function safeParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+/**
+ * Standalone webhook signature verifier (also available as `glytos.webhooks.verify`).
+ * Matches the server scheme: HMAC-SHA256 over `"{timestamp}.{body}"`, sent as
+ * `X-Glytos-Signature: t=<ts>,v1=<hex>`.
+ */
+export function verifyWebhook(
+  payload: string | Buffer,
+  signatureHeader: string,
+  secret: string,
+  toleranceSeconds = 300,
+): boolean {
+  const parts: Record<string, string> = {};
+  for (const piece of signatureHeader.split(',')) {
+    const idx = piece.indexOf('=');
+    if (idx > 0) parts[piece.slice(0, idx).trim()] = piece.slice(idx + 1).trim();
+  }
+  const timestamp = parts['t'];
+  const provided = parts['v1'];
+  if (!timestamp || !provided) return false;
+
+  const body = typeof payload === 'string' ? Buffer.from(payload, 'utf8') : payload;
+  const signed = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), body]);
+  const expected = createHmac('sha256', secret).update(signed).digest('hex');
+
+  const expectedBuf = Buffer.from(expected, 'utf8');
+  const providedBuf = Buffer.from(provided, 'utf8');
+  if (expectedBuf.length !== providedBuf.length) return false;
+  if (!timingSafeEqual(expectedBuf, providedBuf)) return false;
+
+  if (toleranceSeconds > 0) {
+    const ts = Number.parseInt(timestamp, 10);
+    if (!Number.isFinite(ts)) return false;
+    if (Math.abs(Date.now() / 1000 - ts) > toleranceSeconds) return false;
+  }
+  return true;
+}
+
+export default Glytos;