@m8tes/sdk 0.1.0-alpha.1

package/dist/index.d.cts

@@ -0,0 +1,937 @@
+import { Normalizer, M8tesStreamEvent, ConversationState } from './protocol/index.cjs';
+export { APIError, Accumulator, ApiErrorFields, ApprovalRequestEvent, ApprovalResolvedEvent, AuthenticationError, BaseEvent, BillingError, CompactBoundaryEvent, CompactPart, ConflictError, ErrorFromResponseOptions, M8tesApiError, M8tesStreamEventType, MateMessage, MatePart, MateStatus, MessageEndEvent, MessageStartEvent, NotFoundError, NoticeEvent, NoticePart, PROTOCOL_VERSION, PermissionDeniedError, PlanDeltaEvent, PlanEndEvent, PlanStartEvent, ProtocolVersion, QuestionEvent, QuestionItem, QuestionOption, RateLimitError, ReasoningDeltaEvent, ReasoningEndEvent, ReasoningStartEvent, RunCancelledEvent, RunErrorCode, RunErrorEvent, RunFailedError, RunFinishEvent, RunMetricsEvent, RunNotStreamingError, RunStartEvent, RunStatus, RunStatusEvent, SandboxPart, SandboxStatusEvent, SseParserOptions, TERMINAL_EVENT_TYPES, TerminalEventType, TextDeltaEvent, TextEndEvent, TextLikeKind, TextPart, TextStartEvent, ToolInputAvailableEvent, ToolInputDeltaEvent, ToolInputStartEvent, ToolOutputAvailableEvent, ToolPart, ToolState, UnknownEvent, ValidationError, accumulate, createAccumulator, createNormalizer, createSseDecoder, errorClassForStatus, errorFromResponse, initialConversationState, isTerminalEvent, parseErrorEnvelope, parseRetryAfter, parseSse, splitConcatenatedJson } from './protocol/index.cjs';
+
+/**
+ * Server-side transport for the m8tes V2 API.
+ *
+ * SECURITY: this module holds the secret `m8_` API key and must NEVER reach a
+ * browser bundle. Client-side rendering of an agent goes through
+ * `@m8tes/react` + its server proxy, which keeps the key on the server. The
+ * bundle-boundary test asserts `dist/protocol/index.js` contains none of this.
+ *
+ * Retry semantics mirror the Python SDK (`sdk/py/m8tes/_http.py`) exactly so the
+ * two languages behave the same under load:
+ *   - 3 attempts total, 0.5s initial backoff, doubling
+ *   - retry only 429/500/502/503/504
+ *   - retry only idempotent methods (GET/HEAD/PUT/DELETE/OPTIONS). A POST that
+ *     timed out may already have started a billable run, so re-sending it could
+ *     double-charge; those fail immediately and let the caller decide.
+ *   - honour `Retry-After` on 429
+ */
+
+/** Canonical hosted API. Includes the `/api/v2` prefix, like the Python SDK's DEFAULT_BASE_URL. */
+declare const DEFAULT_BASE_URL = "https://api.m8tes.ai/api/v2";
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface ClientOptions {
+    /** Your `m8_` key. Defaults to `process.env.M8TES_API_KEY`. */
+    apiKey?: string;
+    /** Override the API host. Must include the `/api/v2` prefix. */
+    baseUrl?: string;
+    /** Per-request timeout in ms. Default 300_000 (5 min), matching the Python SDK. */
+    timeout?: number;
+    /** Extra headers on every request. */
+    headers?: Record<string, string>;
+    /** Pluggable fetch, for tests or a custom agent/proxy. Default `globalThis.fetch`. */
+    fetch?: FetchLike;
+    /** Reported (not thrown) when a stream frame is unparseable. */
+    onMalformed?: (rawPayload: string, error: unknown) => void;
+}
+interface RequestOptions {
+    body?: unknown;
+    query?: string;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}
+interface StreamRequestOptions extends RequestOptions {
+    /** Reuse a normalizer across reconnects so its dedupe ledger persists. */
+    normalizer?: Normalizer;
+}
+interface Http {
+    baseUrl: string;
+    request<T>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+    /** The OK `Response` itself — for binary bodies (file downloads). Retries and
+     *  typed errors still apply; the caller owns reading the body. */
+    raw(method: string, path: string, opts?: RequestOptions): Promise<Response>;
+    stream(method: string, path: string, opts?: StreamRequestOptions): AsyncGenerator<M8tesStreamEvent, void, unknown>;
+}
+declare function createHttp(options?: ClientOptions): Http;
+
+/**
+ * Cursor pagination over the V2 `ListResponse` envelope (`{data, has_more}`).
+ *
+ * Mirrors the Python SDK's `SyncPage` (`sdk/py/m8tes/_types.py`): a page is the
+ * raw response plus an async iterator that walks every remaining page for you.
+ *
+ * The cursor is the last item's `id`, or its `name` for `/apps` (the one resource
+ * keyed by name). Same rule as Python, so both SDKs paginate identically.
+ */
+interface ListResponse<T> {
+    data: T[];
+    hasMore: boolean;
+}
+/** A page of results. `for await (const item of page)` walks ALL pages. */
+declare class Page<T> implements ListResponse<T>, AsyncIterable<T> {
+    readonly data: T[];
+    readonly hasMore: boolean;
+    /** Fetches the next page given a cursor. Absent on a terminal page. */
+    private readonly fetchNext?;
+    constructor(data: T[], hasMore: boolean, fetchNext?: (startingAfter: string | number) => Promise<Page<T>>);
+    /**
+     * Auto-paging: yields every item across every page.
+     *
+     * Stops if the cursor ever fails to advance. A server that returns the same
+     * page again with `has_more: true` — a caching layer, a replica lagging, a bug
+     * — would otherwise spin forever, re-yielding the same rows and never
+     * returning. Terminating is the only safe response: the caller gets the items
+     * it did see rather than a hung process.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    /** Every item across every page, collected. Prefer iteration for large sets. */
+    all(): Promise<T[]>;
+}
+
+/**
+ * Response types for the resources `@m8tes/sdk` v0.1 covers.
+ *
+ * Field names are the API's own **snake_case**, exactly as sent — the same names
+ * you see in `/docs/api-reference` and in the Python SDK (`sdk/py/m8tes/_types.py`
+ * describes these same objects). Nothing is renamed in transit, so what you read
+ * in the docs is what you type in TypeScript, and a response object is the raw
+ * body. `test/parity.test.ts` asserts these field names against the Python
+ * dataclasses so the two SDKs cannot drift.
+ *
+ * Fields are typed explicitly rather than with an index signature: extra fields
+ * the API adds later still arrive at runtime, they just are not typed until this
+ * file learns them, which is what keeps autocomplete trustworthy.
+ *
+ * Every timestamp is an ISO-8601 string, as sent.
+ */
+/** Free-form JSON, e.g. your own `metadata`. Passed through untouched — the SDK
+ *  never inspects or rewrites keys inside it. */
+type JsonObject = Record<string, unknown>;
+/**
+ * The V2 permission modes. NOT the Claude Agent SDK's mode names — the API
+ * rejects `"acceptEdits"` / `"bypassPermissions"` with a 422.
+ *
+ * Deliberately a closed union with no `| string` escape hatch: widening it to
+ * `string` would accept every typo silently, which is the mistake this type
+ * exists to prevent. If the API gains a mode before this package does, cast at
+ * the call site (`"newMode" as PermissionMode`) and open an issue.
+ */
+type PermissionMode = "autonomous" | "approval" | "plan";
+/** An agent (the API resource is `agents`; `Teammate` is a permanent alias). */
+interface Agent {
+    id: number;
+    name: string;
+    instructions: string | null;
+    tools: string[];
+    role: string | null;
+    goals: string | null;
+    user_id: string | null;
+    metadata: JsonObject | null;
+    default_permission_mode: string;
+    status: string;
+    created_at: string;
+    updated_at?: string | null;
+    model?: string | null;
+    effort?: string | null;
+    allowed_senders?: string[] | null;
+    inbound_email_enabled?: boolean;
+    email_address?: string | null;
+    webhook_enabled?: boolean;
+    webhook_url?: string | null;
+    enable_memory?: boolean | null;
+    enable_history?: boolean | null;
+    enable_task_setup_tools?: boolean | null;
+    enable_feedback?: boolean | null;
+    enable_self_improvement?: boolean | null;
+}
+/** Permanent alias — the platform term is "agent", the DB model is `Teammate`. */
+type Teammate = Agent;
+interface RunUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+    cost_usd?: string | null;
+}
+interface Run {
+    id: number;
+    teammate_id: number | null;
+    status: string;
+    output: string | null;
+    error: string | null;
+    user_id: string | null;
+    metadata: JsonObject | null;
+    created_at: string;
+    updated_at: string | null;
+    task_id?: number | null;
+    permission_mode?: string | null;
+    error_code?: string | null;
+    retryable?: boolean;
+    retry_of_run_id?: number | null;
+    retry_count?: number;
+    output_data?: JsonObject | null;
+    usage?: RunUsage | null;
+}
+/** Condensed run result: what happened, without replaying the transcript. */
+interface RunOutcome {
+    run_id: number;
+    status: string;
+    summary: string | null;
+    headline: string | null;
+    needs_reply: boolean;
+    output_data: JsonObject | null;
+    message_count: number;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    cost_usd: string | null;
+}
+interface RunFile {
+    name: string;
+    size: number;
+}
+interface PermissionRequest {
+    request_id: string;
+    tool_name: string;
+    tool_input: JsonObject | null;
+    status: string;
+    created_at: string;
+    resolved_at: string | null;
+    auto_resolved?: boolean;
+}
+interface Task {
+    id: number;
+    teammate_id: number;
+    name: string | null;
+    instructions: string;
+    tools: string[];
+    expected_output: string | null;
+    goals: string | null;
+    user_id: string | null;
+    status: string;
+    created_at: string;
+    updated_at?: string | null;
+    email_notifications?: boolean;
+    webhook_enabled?: boolean;
+    webhook_url?: string | null;
+    app_trigger_count?: number;
+    enable_memory?: boolean | null;
+    enable_history?: boolean | null;
+    enable_task_setup_tools?: boolean | null;
+    enable_feedback?: boolean | null;
+    enable_lessons?: boolean;
+}
+type TriggerType = "schedule" | "webhook" | "email" | "app";
+interface Trigger {
+    id: number;
+    type: string;
+    enabled: boolean;
+    cron?: string | null;
+    interval_seconds?: number | null;
+    timezone?: string;
+    next_run?: string | null;
+    /** Webhook triggers: the URL to POST to. */
+    url?: string | null;
+    /** Email triggers: the address that starts a run. */
+    address?: string | null;
+    app?: string | null;
+    trigger_name?: string | null;
+    trigger_config?: JsonObject | null;
+}
+/** Toggle result for a webhook or email inbox on an agent or task. */
+interface WebhookToggle {
+    enabled: boolean;
+    url?: string | null;
+}
+interface EmailInbox {
+    enabled: boolean;
+    address?: string | null;
+}
+/** One of your end-users. `user_id` is YOUR id for them; it isolates their data. */
+interface EndUser {
+    id: number;
+    user_id: string;
+    name: string | null;
+    email: string | null;
+    company: string | null;
+    metadata: JsonObject | null;
+    created_at: string;
+    updated_at?: string | null;
+    run_limit?: number | null;
+    cost_limit_cents?: number | null;
+    rate_per_minute?: number | null;
+}
+interface EndUserUsage {
+    id: number;
+    user_id: string;
+    runs_used: number;
+    cost_used: string;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    last_active_at: string | null;
+    runs_limit: number | null;
+    cost_limit_cents: number | null;
+    period_end: string;
+    rate_per_minute?: number | null;
+}
+interface App {
+    name: string;
+    display_name: string;
+    category: string;
+    connected: boolean;
+    auth_type?: string;
+}
+/** Returned by `apps.connectOauth()`. Send the user to `authorization_url`, then
+ *  pass `connection_id` back to `apps.connectComplete()`. */
+interface AppConnectionInitiation {
+    authorization_url: string;
+    connection_id: string;
+}
+interface AppConnectionResult {
+    status: string;
+    connected?: boolean;
+    message?: string | null;
+}
+interface Webhook {
+    id: number;
+    url: string;
+    events: string[];
+    /** Signing secret. Returned on create only — store it, you cannot read it back. */
+    secret: string | null;
+    active: boolean;
+    created_at: string;
+    updated_at?: string | null;
+}
+interface WebhookDelivery {
+    id: number;
+    webhook_endpoint_id: number;
+    event_type: string;
+    event_id: string;
+    run_id: number;
+    status: string;
+    response_status_code: number | null;
+    response_body: string | null;
+    attempts: number;
+    next_retry_at: string | null;
+    created_at: string;
+}
+
+/**
+ * `client.agents` — the reusable agent personas runs execute as.
+ *
+ * The V2 resource is `agents`; `client.teammates` is a permanent alias because
+ * the DB model and older API docs use that name. Mirrors
+ * `sdk/py/m8tes/_resources/teammates.py`.
+ */
+
+interface AgentCreateParams {
+    name?: string;
+    /** The agent's standing instructions: who it is and how it works. */
+    instructions?: string;
+    /** Tool slugs it may use, e.g. `["gmail", "slack"]`. */
+    tools?: string[];
+    role?: string;
+    goals?: string;
+    /** Your id for the end-user who owns this agent. */
+    user_id?: string;
+    metadata?: JsonObject;
+    model?: string;
+    effort?: string;
+    default_permission_mode?: PermissionMode;
+    /** Built-in tool toggles. Omit to inherit the platform default. */
+    enable_memory?: boolean;
+    enable_history?: boolean;
+    enable_task_setup_tools?: boolean;
+    enable_feedback?: boolean;
+    enable_self_improvement?: boolean;
+    /** Give the agent its own email inbox on create. */
+    email_inbox?: boolean;
+    /** Give the agent a webhook trigger URL on create. */
+    webhook?: boolean;
+    /** Start from a prebuilt persona, e.g. `"ppc-manager"`. Template improvements
+     *  keep flowing in on later reads unless you override the field. */
+    from_template?: string;
+}
+/**
+ * PATCH /agents/{id} accepts exactly these fields (backend `TeammateUpdate`).
+ * Create-only fields are NOT here on purpose: sending `webhook` or `email_inbox`
+ * to PATCH returns 200 and silently does nothing, which reads as a working call.
+ * Use `enableWebhook()` / `enableEmailInbox()` instead.
+ *
+ * `null` is meaningful: it CLEARS the field back to the platform default.
+ */
+interface AgentUpdateParams {
+    name?: string | null;
+    instructions?: string | null;
+    tools?: string[] | null;
+    role?: string | null;
+    goals?: string | null;
+    metadata?: JsonObject | null;
+    model?: string | null;
+    effort?: string | null;
+    default_permission_mode?: PermissionMode | null;
+    allowed_senders?: string[] | null;
+    enable_memory?: boolean | null;
+    enable_history?: boolean | null;
+    enable_task_setup_tools?: boolean | null;
+    enable_feedback?: boolean | null;
+    enable_self_improvement?: boolean | null;
+}
+interface AgentListParams {
+    user_id?: string;
+    limit?: number;
+    starting_after?: number;
+}
+interface AgentsResource {
+    create(params?: AgentCreateParams): Promise<Agent>;
+    list(params?: AgentListParams): Promise<Page<Agent>>;
+    get(agentId: number, params?: {
+        user_id?: string;
+    }): Promise<Agent>;
+    update(agentId: number, params: AgentUpdateParams & {
+        user_id?: string;
+    }): Promise<Agent>;
+    delete(agentId: number, params?: {
+        user_id?: string;
+    }): Promise<void>;
+    /** Turn on the webhook trigger; returns the URL to POST to. */
+    enableWebhook(agentId: number): Promise<WebhookToggle>;
+    disableWebhook(agentId: number): Promise<void>;
+    /** Turn on the agent's email inbox; returns the address that starts runs. */
+    enableEmailInbox(agentId: number): Promise<EmailInbox>;
+    disableEmailInbox(agentId: number): Promise<void>;
+}
+
+/**
+ * `client.apps` — the tools agents act in, and each end-user's connections to them.
+ *
+ * Connections are scoped: pass `user_id` and the connection belongs to that
+ * end-user, so the agent acts with THEIR Gmail/Stripe/Slack rather than yours.
+ * In an embed that matters a lot — an account-level connection means a
+ * prompt-injected agent could act on your behalf.
+ *
+ * Mirrors `sdk/py/m8tes/_resources/apps.py`.
+ */
+
+interface AppsResource {
+    /**
+     * Every available tool, with connection status for the given scope.
+     *
+     * NOT paginated and NOT cursor-able: `GET /apps/` accepts only `user_id` and
+     * returns the whole catalog. Sending `limit` or `starting_after` gets a 422
+     * (`unknown_query_parameter`) — verified against a live backend, which is also
+     * how the same bug was found in the published Python SDK. A `Page` is still
+     * returned so `for await` works uniformly across resources.
+     */
+    list(params?: {
+        user_id?: string;
+    }): Promise<Page<App>>;
+    /** True when this app is connected for the given scope. */
+    isConnected(appName: string, params?: {
+        user_id?: string;
+    }): Promise<boolean>;
+    /**
+     * Start an OAuth connection. Send the user to the returned `authorization_url`,
+     * then pass the returned `connection_id` to `connectComplete()`.
+     *
+     * `redirect_uri` is REQUIRED and is spelled `_uri`, not `_url` — the API 422s
+     * on anything else.
+     */
+    connectOauth(appName: string, params: {
+        redirect_uri: string;
+        user_id?: string;
+    }): Promise<AppConnectionInitiation>;
+    /** Connect an app that authenticates with a key instead of OAuth. */
+    connectApiKey(appName: string, params: {
+        api_key: string;
+        user_id?: string;
+    }): Promise<AppConnectionResult>;
+    /** Finish an OAuth connection after the user returns. `connection_id` comes
+     *  from `connectOauth()` and is required. */
+    connectComplete(appName: string, params: {
+        connection_id: string;
+        user_id?: string;
+    }): Promise<AppConnectionResult>;
+    disconnect(appName: string, params?: {
+        user_id?: string;
+    }): Promise<void>;
+}
+
+/**
+ * `RunStream` — the developer-facing view of a streaming run.
+ *
+ * Mirrors the Python SDK's `RunStream` (`sdk/py/m8tes/_streaming.py`): iterate
+ * events, or just await the text. It accumulates as you consume, so after
+ * iterating you have `.text`, `.runId`, and `.errors` without a second request.
+ *
+ * Beyond Python it also exposes `.state` — the full normalized conversation
+ * (messages, tool calls, notices) from the shared protocol accumulator. Useful
+ * server-side for logging what the agent actually did, not just what it said.
+ *
+ * Nothing is consumed until you iterate: constructing a RunStream is free, and
+ * an un-iterated stream is closed by `close()` without reading the body.
+ */
+
+interface RunStreamOptions {
+    /**
+     * Throw `RunFailedError` once iteration finishes if the run emitted any error
+     * event, so a mid-run failure is never mistaken for a successful empty run.
+     * Defaults to false, matching the Python SDK.
+     */
+    raiseOnError?: boolean;
+}
+declare class RunStream implements AsyncIterable<M8tesStreamEvent> {
+    private readonly source;
+    private readonly raiseOnError;
+    private state;
+    private textChunks;
+    private errorMessages;
+    private runIdValue;
+    private consumed;
+    constructor(source: AsyncGenerator<M8tesStreamEvent, void, unknown>, options?: RunStreamOptions);
+    [Symbol.asyncIterator](): AsyncIterator<M8tesStreamEvent>;
+    /** Yield only the assistant's text, in order. The 90% case for a server. */
+    iterText(): AsyncGenerator<string, void, unknown>;
+    /** Drain the stream and return the full assistant text. */
+    text(): Promise<string>;
+    /** Accumulated text so far (complete once iteration finishes). */
+    get output(): string;
+    /** Run id, available as soon as the first `run-start` event arrives. */
+    get runId(): number | null;
+    /** Error messages the run emitted. Check this, or pass `raiseOnError`. */
+    get errors(): string[];
+    get hasErrors(): boolean;
+    /** Full normalized conversation: messages, tool calls, notices, status. */
+    get conversation(): ConversationState;
+    /** Close the underlying response without draining it. */
+    close(): Promise<void>;
+}
+
+/**
+ * `client.runs` — start agents, stream what they do, and answer them mid-run.
+ *
+ * `create()` is the one call most integrations need: it provisions a default
+ * agent if the account has none, so a brand-new key can run an agent in one
+ * request. Mirrors `sdk/py/m8tes/_resources/runs.py`, field for field.
+ */
+
+interface RunCreateParams {
+    /** What the agent should do. */
+    message: string;
+    /** Which agent runs it. Omit to use (or auto-provision) the account default. */
+    agent_id?: number;
+    /** Permanent legacy alias for `agent_id` — the same wire field. */
+    teammate_id?: number;
+    /** Your id for the end-user this run belongs to. Isolates their memory, history, and tool connections. */
+    user_id?: string;
+    /** Tool slugs available for this run. */
+    tools?: string[];
+    /** One-off system instructions for this run. */
+    instructions?: string;
+    /** Name a newly auto-created agent. */
+    name?: string;
+    /** Your own key/value data, echoed back on the Run. */
+    metadata?: JsonObject;
+    model?: string;
+    effort?: string;
+    permission_mode?: PermissionMode;
+    /** Enable clarifying questions, tool approval, and plan mode. */
+    human_in_the_loop?: boolean;
+    /** Run-level overrides for the built-in tools. Omit to inherit the agent default. */
+    memory?: boolean;
+    history?: boolean;
+    task_setup_tools?: boolean;
+    feedback?: boolean;
+    /** Ask for structured output matching this JSON Schema; lands on `run.output_data`. */
+    output_schema?: JsonObject;
+    /** Give this run's agent an email inbox. */
+    email_inbox?: boolean;
+}
+interface RunListParams {
+    user_id?: string;
+    agent_id?: number;
+    teammate_id?: number;
+    task_id?: number;
+    status?: string;
+    limit?: number;
+    starting_after?: number;
+}
+interface ApproveParams {
+    /** From the `approval-request` event, or `runs.permissions()`. */
+    request_id: string;
+    decision: "allow" | "deny";
+    /**
+     * Apply the same decision to matching tool requests for the rest of THIS run.
+     * For a policy that outlives the run, use the permissions API instead.
+     */
+    remember?: boolean;
+}
+interface AnswerParams {
+    /**
+     * Question text → the option label you picked. The keys must be the exact
+     * `question` strings from the `question` event.
+     */
+    answers: Record<string, string>;
+}
+interface RunsResource {
+    /** Start a run and stream it. */
+    create(params: RunCreateParams, options?: RunStreamOptions): RunStream;
+    /** Start a run and return immediately; poll `get()` or use a webhook for the result. */
+    createAsync(params: RunCreateParams): Promise<Run>;
+    /** Join a run already in flight. Throws `RunNotStreamingError` if it has finished. */
+    stream(runId: number, options?: RunStreamOptions): RunStream;
+    /** Continue the conversation on an existing run, streaming the reply. */
+    reply(runId: number, message: string, options?: RunStreamOptions): RunStream;
+    /** GET /runs/{id} takes NO query params — it is already account-scoped, and
+     *  sending `user_id` returns 422 `unknown_query_parameter`. */
+    get(runId: number): Promise<Run>;
+    list(params?: RunListParams): Promise<Page<Run>>;
+    /** Cancel a running run. Returns the updated Run, like the Python SDK. */
+    cancel(runId: number): Promise<Run>;
+    /** Approve or deny a pending tool-permission gate. */
+    approve(runId: number, params: ApproveParams): Promise<PermissionRequest>;
+    /** Answer a pending AskUserQuestion gate, resuming the run. */
+    answer(runId: number, params: AnswerParams): Promise<{
+        status: string;
+        resumed: boolean;
+    }>;
+    /** Gates currently waiting on a human. */
+    permissions(runId: number): Promise<PermissionRequest[]>;
+    /** Condensed result: headline, summary, tokens, cost. */
+    outcome(runId: number): Promise<RunOutcome>;
+    /** Files the agent produced. */
+    files(runId: number): Promise<RunFile[]>;
+    /** Download one produced file. */
+    downloadFile(runId: number, filename: string): Promise<ArrayBuffer>;
+}
+
+/**
+ * `client.settings` — account-level configuration.
+ *
+ * In v0.1 scope for one concrete reason: strict multi-tenant mode
+ * (`require_end_user_id`) is ON by default for API accounts, and when it rejects a
+ * request the backend's own 422 message says "turn it off once with
+ * client.settings.update(require_end_user_id=False)". Without this resource a
+ * TypeScript developer would follow that instruction into a method that does not
+ * exist. Found by running the SDK against a real backend.
+ *
+ * Mirrors `sdk/py/m8tes/_resources/settings.py`.
+ */
+
+interface AccountSettings {
+    /** Per-end-user monthly run cap. null = uncapped. */
+    per_end_user_run_limit: number | null;
+    /** Per-end-user monthly metered spend cap, in cents. null = uncapped. */
+    per_end_user_cost_limit_cents: number | null;
+    /** Per-end-user run-starts per minute. null = unthrottled. */
+    per_end_user_rate_per_minute: number | null;
+    /** "standard", or "metadata_only" for zero data retention. */
+    retention_mode: string;
+    /** When true, any request that would fall back to the account scope is rejected. */
+    require_end_user_id: boolean;
+}
+interface AccountSettingsUpdateParams {
+    /** Pass a number to set, `null` to clear, omit to leave unchanged. */
+    per_end_user_run_limit?: number | null;
+    per_end_user_cost_limit_cents?: number | null;
+    per_end_user_rate_per_minute?: number | null;
+    retention_mode?: "standard" | "metadata_only";
+    /**
+     * Strict multi-tenant mode. ON by default for API accounts: a request that
+     * omits `user_id` and would therefore land in the account-level scope is
+     * rejected with a 422 rather than silently assuming the global scope.
+     *
+     * Set false only if you are building for yourself (single-tenant).
+     */
+    require_end_user_id?: boolean;
+}
+interface SettingsResource {
+    get(): Promise<AccountSettings>;
+    update(params: AccountSettingsUpdateParams): Promise<AccountSettings>;
+}
+
+/**
+ * `client.tasks` — reusable work definitions, plus the triggers that fire them.
+ *
+ * A task is "what to do"; a trigger is "when". `client.tasks.triggers` covers all
+ * four kinds (schedule, webhook, email, app event). Mirrors
+ * `sdk/py/m8tes/_resources/tasks.py`.
+ */
+
+/** A task must belong to an agent: `POST /tasks/` requires `teammate_id`, so the
+ *  type requires one of the two spellings rather than letting you discover it as
+ *  a 422. */
+type TaskOwner = {
+    agent_id: number;
+    teammate_id?: never;
+} | {
+    teammate_id: number;
+    agent_id?: never;
+};
+type TaskCreateParams = TaskOwner & TaskCreateFields;
+interface TaskCreateFields {
+    /** What the agent should do each time this task runs. */
+    instructions: string;
+    name?: string;
+    tools?: string[];
+    /** What a good result looks like. */
+    expected_output?: string;
+    goals?: string;
+    user_id?: string;
+    /** Email the account owner when a run finishes. Default true. */
+    email_notifications?: boolean;
+    /** Create a webhook trigger alongside the task. */
+    webhook?: boolean;
+    /** Cron expression, e.g. `"0 9 * * 1-5"`. Creates a schedule trigger. */
+    schedule?: string;
+    /** IANA timezone for `schedule`. Default "UTC". */
+    schedule_timezone?: string;
+    enable_memory?: boolean;
+    enable_history?: boolean;
+    enable_task_setup_tools?: boolean;
+    enable_feedback?: boolean;
+    /** Accumulate self-improvement lessons across this task's runs. Default true. */
+    enable_lessons?: boolean;
+}
+/**
+ * PATCH /tasks/{id} accepts exactly these fields (backend `DevTaskUpdate`).
+ * `schedule`, `schedule_timezone`, `webhook`, and the agent id are create-only:
+ * sending them to PATCH returns 200 and changes nothing. Change a schedule via
+ * `tasks.triggers.update()`, and a webhook via `enableWebhook()`.
+ *
+ * `null` is meaningful: it CLEARS the field.
+ */
+interface TaskUpdateParams {
+    name?: string | null;
+    instructions?: string | null;
+    tools?: string[] | null;
+    expected_output?: string | null;
+    goals?: string | null;
+    email_notifications?: boolean | null;
+    enable_memory?: boolean | null;
+    enable_history?: boolean | null;
+    enable_task_setup_tools?: boolean | null;
+    enable_feedback?: boolean | null;
+    enable_lessons?: boolean | null;
+}
+interface TaskListParams {
+    user_id?: string;
+    agent_id?: number;
+    teammate_id?: number;
+    status?: string;
+    limit?: number;
+    starting_after?: number;
+}
+interface TriggerCreateParams {
+    type: TriggerType | string;
+    /** Schedule triggers: a cron expression. */
+    cron?: string;
+    /** Schedule triggers: a plain interval instead of cron. */
+    interval_seconds?: number;
+    /** IANA timezone. Default "UTC". */
+    timezone?: string;
+    /** App-event triggers: the app slug, e.g. `"github"`. */
+    app?: string;
+    /** App-event triggers: the event name, e.g. `"pull_request_opened"`. */
+    trigger_name?: string;
+    trigger_config?: JsonObject;
+    user_id?: string;
+    /** Email triggers: only these senders may start a run. */
+    allowed_senders?: string[];
+}
+interface TriggersResource {
+    create(taskId: number, params: TriggerCreateParams): Promise<Trigger>;
+    list(taskId: number): Promise<Trigger[]>;
+    /** Only the schedule shape and the enabled flag are mutable — a trigger's
+     *  `type`/`app`/`trigger_name` are fixed at creation and are silently ignored
+     *  on PATCH. Delete and recreate to change those. */
+    update(taskId: number, triggerId: number, params: {
+        cron?: string;
+        interval_seconds?: number;
+        timezone?: string;
+        enabled?: boolean;
+    }): Promise<Trigger>;
+    delete(taskId: number, triggerId: number): Promise<void>;
+}
+interface TasksResource {
+    triggers: TriggersResource;
+    create(params: TaskCreateParams): Promise<Task>;
+    list(params?: TaskListParams): Promise<Page<Task>>;
+    get(taskId: number, params?: {
+        user_id?: string;
+    }): Promise<Task>;
+    update(taskId: number, params: TaskUpdateParams & {
+        user_id?: string;
+    }): Promise<Task>;
+    delete(taskId: number, params?: {
+        user_id?: string;
+    }): Promise<void>;
+    /** Run the task now, streaming it. */
+    run(taskId: number, params?: {
+        user_id?: string;
+    }, options?: RunStreamOptions): RunStream;
+    /** Run the task now without streaming; poll `runs.get()` for the result. */
+    runAsync(taskId: number, params?: {
+        user_id?: string;
+    }): Promise<Run>;
+    enableWebhook(taskId: number): Promise<WebhookToggle>;
+    disableWebhook(taskId: number): Promise<void>;
+}
+
+/**
+ * `client.users` — your end-users, the multi-tenancy boundary.
+ *
+ * `user_id` is YOUR identifier for a customer; the platform stores it as
+ * `end_user_id` and isolates that person's memory, run history, and tool
+ * connections strictly. There is no fallback to account-level data.
+ *
+ * Registering an end-user here is optional — passing `user_id` on a run creates
+ * them implicitly. Do it explicitly when you want per-user budgets and rate
+ * limits. Mirrors `sdk/py/m8tes/_resources/users.py`.
+ */
+
+interface EndUserCreateParams {
+    /** Your id for this person. Any stable string. */
+    user_id: string;
+    name?: string;
+    email?: string;
+    company?: string;
+    metadata?: JsonObject;
+    /** Cap this end-user's runs per billing period. */
+    run_limit?: number;
+    /** Cap this end-user's spend per billing period, in cents. */
+    cost_limit_cents?: number;
+    /** Cap this end-user's runs per minute. Exceeding it returns 429. */
+    rate_per_minute?: number;
+}
+/** `null` CLEARS a cap (inherit the account default); omitting leaves it alone. */
+interface EndUserUpdateParams {
+    name?: string | null;
+    email?: string | null;
+    company?: string | null;
+    metadata?: JsonObject | null;
+    run_limit?: number | null;
+    cost_limit_cents?: number | null;
+    rate_per_minute?: number | null;
+}
+interface PageParams {
+    limit?: number;
+    starting_after?: number;
+}
+interface UsersResource {
+    create(params: EndUserCreateParams): Promise<EndUser>;
+    list(params?: PageParams): Promise<Page<EndUser>>;
+    get(userId: string): Promise<EndUser>;
+    update(userId: string, params: EndUserUpdateParams): Promise<EndUser>;
+    delete(userId: string): Promise<void>;
+    /** Per-end-user token, run, and cost usage against their limits. */
+    usage(params?: PageParams & {
+        user_id?: string;
+    }): Promise<Page<EndUserUsage>>;
+}
+
+/**
+ * `client.webhooks` — outbound event delivery, plus signature verification.
+ *
+ * `verifySignature` is the one function every webhook receiver needs, so it is
+ * also exported standalone from the package root: verifying does not require a
+ * client or an API key. Mirrors `sdk/py/m8tes/_resources/webhooks.py` byte for
+ * byte on the signing scheme, so a payload verified by one SDK verifies in the
+ * other.
+ *
+ * Scheme: HMAC-SHA256 over `"{webhook-id}.{webhook-timestamp}.{raw body}"`, hex,
+ * prefixed `v1=`, compared in constant time.
+ */
+
+interface VerifySignatureOptions {
+    /**
+     * Reject signatures whose timestamp is older (or newer) than this many
+     * seconds — replay protection. Omit to skip the check. 300 is a good default
+     * for a public endpoint.
+     */
+    toleranceSeconds?: number;
+    /** Injectable clock, for tests. Seconds since epoch. */
+    now?: () => number;
+}
+/**
+ * Verify a m8tes webhook signature.
+ *
+ * Pass the RAW request body — a parsed-and-restringified object will not match,
+ * because JSON.stringify does not preserve key order or spacing.
+ *
+ * ```ts
+ * const raw = await req.text();
+ * if (!verifySignature(raw, Object.fromEntries(req.headers), secret, { toleranceSeconds: 300 })) {
+ *   return new Response("bad signature", { status: 401 });
+ * }
+ * ```
+ */
+declare function verifySignature(body: string | Uint8Array, headers: Record<string, string | string[] | undefined> | Headers, secret: string, options?: VerifySignatureOptions): boolean;
+interface WebhooksResource {
+    verifySignature: typeof verifySignature;
+    /** Register an endpoint. The signing secret is returned ONLY here — store it. */
+    create(params: {
+        url: string;
+        events?: string[];
+    }): Promise<Webhook>;
+    list(params?: {
+        limit?: number;
+        starting_after?: number;
+    }): Promise<Page<Webhook>>;
+    get(webhookId: number): Promise<Webhook>;
+    update(webhookId: number, params: {
+        url?: string;
+        events?: string[];
+        active?: boolean;
+    }): Promise<Webhook>;
+    delete(webhookId: number): Promise<void>;
+    /** Delivery attempts, for debugging a receiver that is not getting events. */
+    listDeliveries(webhookId: number, params?: {
+        limit?: number;
+        starting_after?: number;
+    }): Promise<Page<WebhookDelivery>>;
+}
+
+/**
+ * `@m8tes/sdk` — TypeScript client for the m8tes API.
+ *
+ * ```ts
+ * import { M8tes } from "@m8tes/sdk";
+ *
+ * const client = new M8tes(); // reads M8TES_API_KEY
+ *
+ * const run = client.runs.create({
+ *   message: "A customer asked to cancel. Draft a warm reply offering to pause instead.",
+ *   userId: "customer_42", // isolates this end-user's memory, history, and connections
+ * });
+ * for await (const chunk of run.iterText()) process.stdout.write(chunk);
+ * ```
+ *
+ * SECURITY: this entry point holds your secret `m8_` key and is server-only.
+ * Never import it from client-side code. To render an agent in a browser, use
+ * `@m8tes/react` plus its server proxy, which keeps the key on your server.
+ *
+ * The streaming wire protocol lives in `@m8tes/sdk/protocol` (browser-safe, no
+ * auth) so this package and `@m8tes/react` share one implementation.
+ */
+
+/** Kept in lockstep with package.json "version" — guarded by test/version.test.ts. */
+declare const M8TES_SDK_VERSION = "0.1.0-alpha.1";
+declare class M8tes {
+    readonly runs: RunsResource;
+    readonly agents: AgentsResource;
+    /** Permanent alias for `agents` — the DB model and older docs say "teammate". */
+    readonly teammates: AgentsResource;
+    readonly tasks: TasksResource;
+    readonly users: UsersResource;
+    readonly apps: AppsResource;
+    readonly webhooks: WebhooksResource;
+    readonly settings: SettingsResource;
+    /** The underlying transport. Use it to call an endpoint this version does not wrap yet. */
+    readonly http: Http;
+    constructor(options?: ClientOptions);
+}
+
+export { type AccountSettings, type AccountSettingsUpdateParams, type Agent, type AgentCreateParams, type AgentListParams, type AgentUpdateParams, type AgentsResource, type App, type AppConnectionInitiation, type AppConnectionResult, type AppsResource, type ClientOptions, ConversationState, DEFAULT_BASE_URL, type EmailInbox, type EndUser, type EndUserCreateParams, type EndUserUpdateParams, type EndUserUsage, type FetchLike, type Http, type JsonObject, type ListResponse, M8TES_SDK_VERSION, M8tes, M8tesStreamEvent, Normalizer, Page, type PageParams, type PermissionMode, type PermissionRequest, type Run, type RunCreateParams, type RunFile, type RunListParams, type RunOutcome, RunStream, type RunStreamOptions, type RunUsage, type RunsResource, type SettingsResource, type Task, type TaskCreateParams, type TaskListParams, type TaskUpdateParams, type TasksResource, type Teammate, type Trigger, type TriggerCreateParams, type TriggerType, type TriggersResource, type UsersResource, type VerifySignatureOptions, type Webhook, type WebhookDelivery, type WebhookToggle, type WebhooksResource, createHttp, verifySignature };