@m8tes/sdk 0.1.0-alpha.5 → 0.1.0-alpha.6

package/dist/index.d.cts

@@ -214,6 +214,19 @@ interface Run {
     retry_count?: number;
     output_data?: JsonObject | null;
     usage?: RunUsage | null;
+    /**
+     * Which meter the run settles on: "api" (prepaid balance — end-user-scoped /
+     * embedding work) or "platform" (subscription plan — first-party work, INCLUDING
+     * the account's own API-key calls). Stamped at creation.
+     */
+    billing_surface?: string;
+    /**
+     * Where the run came in: "api", "app", "cli", "email", "slack", "imessage",
+     * "webhook". Attribution only, never billing — a first-party API-key call is
+     * channel "api" but billing_surface "platform", so filtering a developer view
+     * on surface alone hides your own traffic.
+     */
+    channel?: string | null;
 }
 /** Condensed run result: what happened, without replaying the transcript. */
 interface RunOutcome {
@@ -244,10 +257,15 @@ interface PermissionRequest {
     created_at: string;
     resolved_at: string | null;
     auto_resolved?: boolean;
+    /** Actual saved cross-run grant outcome, also present on listings. Null means unknown. */
+    remembered?: boolean | null;
     /** False when the runtime would ignore an "always allow" for this tool. */
     can_remember?: boolean;
     /** False when the Always-allow control must start unticked (force-ask floor). */
     remember_default?: boolean;
+    ask_reason?: string;
+    surface?: string;
+    surface_label?: string | null;
 }
 interface Task {
     id: number;
@@ -409,6 +427,8 @@ interface Webhook {
     /** Signing secret. Returned on create only — store it, you cannot read it back. */
     secret: string | null;
     active: boolean;
+    /** End-user scope. Null/omitted = account-level. */
+    user_id?: string | null;
     created_at: string;
     updated_at?: string | null;
 }
@@ -442,12 +462,12 @@ interface WebhookDelivery {
     next_retry_at: string | null;
     created_at: string;
 }
-/** A standing tool permission policy: one pre-approved tool for one end-user.
- *  Note the asymmetry — you create it with `tool`, the API returns it as
- *  `tool_name`. */
+/** A standing tool permission policy: one pre-approved tool for one scope.
+ *  `user_id` is null for the account-level scope. Note the asymmetry — you
+ *  create it with `tool`, the API returns it as `tool_name`. */
 interface PermissionPolicy {
     id: number;
-    user_id: string;
+    user_id: string | null;
     tool_name: string;
     created_at: string;
     /** Which surface minted the grant ("run_approval" / "api"); null on legacy rows. */
@@ -469,7 +489,9 @@ interface Usage {
     cost_limit: string;
     period_end: string;
     subscription_status: string | null;
-    /** Authoritative eligibility for the model-subscription-funded Free path. */
+    /** Current paid subscription cadence, when known. */
+    subscription_billing_period?: "monthly" | "annual" | null;
+    /** Authoritative eligibility for the model-subscription-funded Hobby path. */
     free_path_available: boolean;
     overage_enabled: boolean;
     overage_used_cents: number;
@@ -518,7 +540,7 @@ interface Receipt {
     receipt_url: string | null;
     created_at: string;
 }
-/** A public (paid) plan from the canonical catalog. All prices in cents. */
+/** A public Hobby or paid plan from the canonical catalog. All prices in cents. */
 interface Plan {
     slug: string;
     display_name: string;
@@ -526,9 +548,20 @@ interface Plan {
     monthly_price_cents: number;
     annual_price_cents: number;
     overage_rate_cents: number;
+    /** `own_subscription` uses the customer's connected model plan; `platform` includes inference. */
+    inference_mode: "own_subscription" | "platform";
+    /** Whether this plan may opt into metered usage beyond its included runs. */
+    overage_available: boolean;
     /** Per-period model-spend fair-use cap; `0` on servers that predate the field. */
     fair_use_cost_limit_cents: number;
 }
+type SubscriptionPlanId = "individual" | "pro" | "max_5x" | "max_20x";
+type SubscriptionBillingPeriod = "monthly" | "annual";
+/** Stripe redirect returned when starting checkout or managing the current plan. */
+interface SubscriptionCheckout {
+    url: string;
+    destination: "checkout" | "portal" | "sales";
+}
 /** One prepaid token-balance ledger entry. Micro-USD; debits are negative. */
 interface TokenTransaction {
     type: string;
@@ -842,6 +875,18 @@ interface OverageParams {
     /** Hard ceiling on overage spend per period, in cents. */
     monthly_cap_cents: number;
 }
+interface SubscriptionCheckoutParams {
+    plan_id: SubscriptionPlanId;
+    billing_period?: SubscriptionBillingPeriod;
+}
+interface BillingPortalParams {
+    /** Kept for wire compatibility; `subscription_update` returns a sales-contact URL. */
+    flow?: "subscription_update";
+}
+interface BillingPlansParams {
+    /** Include Hobby, which is activated separately and cannot be submitted to checkout. */
+    include_free?: boolean;
+}
 interface TopupParams {
     /** Cents to add. $5 minimum, $1M maximum. */
     amount_cents: number;
@@ -883,13 +928,19 @@ interface BillingResource {
      * `receipt_url` can be `null` when Stripe can no longer retrieve the session.
      */
     receipts(params?: PageParams): Promise<Page<Receipt>>;
-    /** What the paid plans include and cost — for your own pricing page or upgrade
-     *  prompt. Public (paid) plans only, straight from the canonical catalog, and
-     *  returned as a plain array rather than a page. */
-    plans(): Promise<Plan[]>;
+    /** Purchasable plans from the canonical catalog. Pass `include_free` to also render Hobby. */
+    plans(params?: BillingPlansParams): Promise<Plan[]>;
+    /** Start a paid subscription. Existing customers may manage their current tier and cadence;
+     *  changing either returns `destination="sales"` with a contact URL. */
+    checkout(params: SubscriptionCheckoutParams): Promise<SubscriptionCheckout>;
+    /** Open Stripe for payment methods, invoices, or cancellation. */
+    portal(params?: BillingPortalParams): Promise<string>;
+    /** Activate Hobby using a connected model subscription. */
+    activateFree(): Promise<Usage>;
     /**
      * Decide whether runs may continue past your plan's included allotment, and how
-     * far. Off by default; once enabled, extra runs bill at the per-run overage rate
+     * far. Available only when the current catalog plan has `overage_available=true`.
+     * Off by default; once enabled, extra runs bill at the per-run overage rate
      * until `monthly_cap_cents` is reached. Returns the refreshed usage so you can
      * confirm the new state without a second call.
      */
@@ -1026,6 +1077,7 @@ interface ModelConnection {
     provider: ModelConnectionProvider;
     display_name: string;
     connected: boolean;
+    is_default: boolean;
     status?: string | null;
     account_label?: string | null;
     expires_at?: string | null;
@@ -1060,46 +1112,72 @@ interface ModelConnectionsResource {
 declare function createModelConnectionsResource(http: Http): ModelConnectionsResource;
 
 /**
- * `client.permissions` — standing tool allow-lists, one end-user at a time.
+ * `client.permissions` — standing tool allow-lists.
  *
  * A run pauses whenever the agent reaches for a tool that is not pre-approved,
  * and stays paused until somebody answers. That is the right default for a first
  * run and the wrong one for a tool your product has already decided is fine. A
- * policy here says "this end-user's runs may use this tool" once, so their runs
- * stop stopping.
+ * policy here says "these runs may use this tool" once, so they stop stopping.
  *
- * Scope: policies are per end-user (`user_id` is required on every call — there
- * is no account-wide policy) and outlive the run, unlike `runs.answerPermission()`
- * which unblocks a single gate. `/docs/users` documents this surface; mirrors
+ * TWO SCOPES, and `user_id` is what selects between them — it is not a required
+ * argument. Pass it to reach one end-user's policies. OMIT it to reach the
+ * ACCOUNT-LEVEL scope (`end_user_id IS NULL`), which is the scope a run with no
+ * `user_id` matches and the one the platform writes to when somebody picks
+ * "always allow" on a first-party run. Requiring `user_id` here is exactly what
+ * made those policies ungovernable — grantable, but never listable or revocable
+ * through this SDK. The API stopped requiring it on 2026-08-01
+ * (`PermissionPolicyCreate.user_id`, `_end_user_id_query`); this client did not
+ * follow, and its own docstring asserted the account scope did not exist.
+ *
+ * The two scopes never overlap: a delete must name the SAME scope the policy
+ * lives in, so an end-user-scoped delete cannot reach an account-level policy
+ * (404), and neither can the reverse.
+ *
+ * One account setting narrows this: with strict multi-tenant mode on
+ * (`require_end_user_id`, the default for API-key signups) the server rejects a
+ * programmatic call that resolves to no end-user with a 422 naming the setting.
+ * Omitting `user_id` is still how you ASK for the account scope — on those
+ * accounts the answer is just no.
+ *
+ * Policies outlive the run, unlike `runs.answerPermission()` which unblocks a
+ * single gate. `/docs/users` documents this surface; mirrors
  * `sdk/py/m8tes/_resources/permissions.py`.
  */
 
 interface PermissionCreateParams {
-    /** The end-user whose runs this policy applies to. Required — policies never span end-users. */
-    user_id: string;
+    /**
+     * The end-user whose runs this policy applies to. Omit for the account-level
+     * scope — the one runs that carry no `user_id` match.
+     */
+    user_id?: string;
     /** The tool to pre-approve, e.g. `"Bash"` or an `mcp__*` tool name. */
     tool: string;
 }
 interface PermissionListParams extends PageParams {
-    /** Required: you list one end-user's policies, never the account's. */
-    user_id: string;
+    /** One end-user's policies. Omit to list the account-level scope. */
+    user_id?: string;
+}
+interface PermissionDeleteParams {
+    /**
+     * The scope the policy lives in. Omit to delete an account-level policy.
+     * A scope that does not match the policy is a 404, never a silent no-op.
+     */
+    user_id?: string;
 }
 interface PermissionsResource {
     /**
-     * Pre-approve a tool so this end-user's runs no longer pause on it.
+     * Pre-approve a tool so matching runs no longer pause on it.
      * Idempotent — re-approving the same tool returns the existing policy rather
      * than erroring or duplicating. Send `tool`; the policy comes back as `tool_name`.
      */
     create(params: PermissionCreateParams): Promise<PermissionPolicy>;
-    /** Audit what an end-user's runs are allowed to do without asking. */
-    list(params: PermissionListParams): Promise<Page<PermissionPolicy>>;
+    /** Audit what one scope's runs are allowed to do without asking. */
+    list(params?: PermissionListParams): Promise<Page<PermissionPolicy>>;
     /**
      * Revoke a pre-approval, so the tool gates again on the next run.
-     * `user_id` is required and scopes the delete — an id alone will not resolve.
+     * `user_id` scopes the delete and must match the policy's own scope.
      */
-    delete(permissionId: number, params: {
-        user_id: string;
-    }): Promise<void>;
+    delete(permissionId: number, params?: PermissionDeleteParams): Promise<void>;
 }
 declare function createPermissionsResource(http: Http): PermissionsResource;
 
@@ -1192,6 +1270,7 @@ interface PollDeps {
     }, signal?: AbortSignal): Promise<unknown>;
     answer(runId: number, params: {
         answers: Record<string, string>;
+        request_id?: string;
     }, signal?: AbortSignal): Promise<unknown>;
 }
 /** Thrown when the caller aborts the wait. */
@@ -1357,6 +1436,10 @@ interface RunListParams {
     teammate_id?: number;
     task_id?: number;
     status?: string;
+    /** `created` (newest first, the default) or `priority` (runs waiting on a human first). */
+    sort?: "created" | "priority";
+    /** Hide Company Agent Day-1 / pulse / maintenance (Platform accounts only) — ask whether the user has run anything. */
+    exclude_platform_runs?: boolean;
     limit?: number;
     starting_after?: number;
 }
@@ -1374,6 +1457,13 @@ interface ApproveParams {
      *   stored policy).
      */
     remember?: boolean;
+    /**
+     * Steering in your own words, e.g. with `decision: "deny"`, "use the staging
+     * board instead". The agent reads it and adapts rather than silently skipping
+     * the action. Delivered on both decisions when the run is paused; a deny's
+     * reason also reaches a still-live run.
+     */
+    reason?: string;
 }
 interface AnswerParams {
     /**
@@ -1381,6 +1471,20 @@ interface AnswerParams {
      * `question` strings from the `question` event.
      */
     answers: Record<string, string>;
+    /**
+     * The gate this answer is for — `requestId` off the `question` event (the
+     * stream normalises it to camelCase), or `request_id` from
+     * `runs.permissions()`. Required whenever the run has more than one
+     * unresolved `AskUserQuestion`.
+     *
+     * A run accumulates asks over its life, and only some of them get resolved.
+     * With no `request_id` the server does not know which one you answered, so it
+     * falls back to position: the OLDEST ask that is not already allowed. A gate
+     * that timed out earlier still matches that, so the answer you wrote for the
+     * live question is merged into the stale one and the run resumes on the wrong
+     * selection. Send the id and the server targets exactly that gate.
+     */
+    request_id?: string;
 }
 interface RunsResource {
     /** Start a run and stream it. */
@@ -1430,7 +1534,11 @@ interface RunsResource {
     }): 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 a pending AskUserQuestion gate, resuming the run. Pass `request_id`
+     * when the run has more than one unresolved ask, or the server picks by
+     * position instead.
+     */
     answer(runId: number, params: AnswerParams): Promise<{
         status: string;
         resumed: boolean;
@@ -1649,6 +1757,9 @@ interface TasksResource {
  * byte on the signing scheme, so a payload verified by one SDK verifies in the
  * other.
  *
+ * `user_id` scopes an endpoint to one end-user; omit for account-level. The
+ * scopes never mix: an end-user run only delivers to that end-user's endpoints.
+ *
  * Scheme: HMAC-SHA256 over `"{webhook-id}.{webhook-timestamp}.{raw body}"`, hex,
  * prefixed `v1=`, compared in constant time.
  */
@@ -1683,22 +1794,31 @@ interface WebhooksResource {
     create(params: {
         url: string;
         events?: string[];
+        user_id?: string;
     }): Promise<Webhook>;
     list(params?: {
         limit?: number;
         starting_after?: number;
+        user_id?: string;
     }): Promise<Page<Webhook>>;
-    get(webhookId: number): Promise<Webhook>;
+    get(webhookId: number, params?: {
+        user_id?: string;
+    }): Promise<Webhook>;
     update(webhookId: number, params: {
         url?: string;
         events?: string[];
         active?: boolean;
+        rotate_secret?: boolean;
+        user_id?: string;
     }): Promise<Webhook>;
-    delete(webhookId: number): Promise<void>;
+    delete(webhookId: number, params?: {
+        user_id?: string;
+    }): Promise<void>;
     /** Delivery attempts, for debugging a receiver that is not getting events. */
     listDeliveries(webhookId: number, params?: {
         limit?: number;
         starting_after?: number;
+        user_id?: string;
     }): Promise<Page<WebhookDelivery>>;
 }
 
@@ -1726,7 +1846,7 @@ interface WebhooksResource {
  */
 
 /** Kept in lockstep with package.json "version" — guarded by test/version.test.ts. */
-declare const M8TES_SDK_VERSION = "0.1.0-alpha.5";
+declare const M8TES_SDK_VERSION = "0.1.0-alpha.6";
 declare class M8tes {
     readonly runs: RunsResource;
     readonly agents: AgentsResource;
@@ -1748,4 +1868,4 @@ declare class M8tes {
     constructor(options?: ClientOptions);
 }
 
-export { type AccountDeletion, type AccountExport, type AccountResource, type AccountSettings, type AccountSettingsUpdateParams, type Agent, type AgentCreateParams, type AgentListParams, type AgentUpdateParams, type AgentsResource, type AlertThresholdParams, type App, type AppConnectionInitiation, type AppConnectionResult, type AppsResource, type AuthorizableModelConnectionProvider, type AutoReloadParams, type Balance, type BillingResource, type ClientOptions, type CodeModelConnectionProvider, ConversationState, DEFAULT_BASE_URL, type DeviceModelConnectionProvider, type EmailInbox, type EndUser, type EndUserCreateParams, type EndUserUpdateParams, type EndUserUsage, type FetchLike, type Http, type JsonObject, type ListResponse, M8TES_SDK_VERSION, M8tes, M8tesStreamEvent, type MemoriesResource, type Memory, type MemoryCreateParams, type MemoryListParams, type MemoryUpdateParams, type Model, type ModelAuthorization, type ModelConnection, type ModelConnectionProvider, type ModelConnectionsResource, type ModelPricing, type ModelsResource, Normalizer, type OverageParams, Page, type PageParams, type PermissionCreateParams, type PermissionListParams, type PermissionMode, type PermissionPolicy, type PermissionRequest, type PermissionsResource, type Plan, type PollOptions, type Receipt, type Run, type RunCreateParams, type RunFile, type RunListParams, type RunOutcome, RunPausedError, RunStream, type RunStreamOptions, RunTimeoutError, type RunUsage, RunWaitAbortedError, type RunsResource, type SettingsResource, TERMINAL_STATUSES, type Task, type TaskCreateParams, type TaskListParams, type TaskRunParams, type TaskUpdateParams, type TasksResource, type Teammate, type TokenTransaction, type TopupParams, type Trigger, type TriggerCreateParams, type TriggerType, type TriggersResource, type Usage, type UsageBucket, type UsageModelSlice, type UsageTimeseries, type UsageTimeseriesParams, type UsageTotals, type UsersResource, type VerifySignatureOptions, type WaitOptions, type Webhook, type WebhookDelivery, type WebhookToggle, type WebhooksResource, createAccountResource, createBillingResource, createHttp, createMemoriesResource, createModelConnectionsResource, createModelsResource, createPermissionsResource, isPlanApproval, planText, pollRun, verifySignature, waitForRun };
+export { type AccountDeletion, type AccountExport, type AccountResource, type AccountSettings, type AccountSettingsUpdateParams, type Agent, type AgentCreateParams, type AgentListParams, type AgentUpdateParams, type AgentsResource, type AlertThresholdParams, type App, type AppConnectionInitiation, type AppConnectionResult, type AppsResource, type AuthorizableModelConnectionProvider, type AutoReloadParams, type Balance, type BillingPlansParams, type BillingPortalParams, type BillingResource, type ClientOptions, type CodeModelConnectionProvider, ConversationState, DEFAULT_BASE_URL, type DeviceModelConnectionProvider, type EmailInbox, type EndUser, type EndUserCreateParams, type EndUserUpdateParams, type EndUserUsage, type FetchLike, type Http, type JsonObject, type ListResponse, M8TES_SDK_VERSION, M8tes, M8tesStreamEvent, type MemoriesResource, type Memory, type MemoryCreateParams, type MemoryListParams, type MemoryUpdateParams, type Model, type ModelAuthorization, type ModelConnection, type ModelConnectionProvider, type ModelConnectionsResource, type ModelPricing, type ModelsResource, Normalizer, type OverageParams, Page, type PageParams, type PermissionCreateParams, type PermissionDeleteParams, type PermissionListParams, type PermissionMode, type PermissionPolicy, type PermissionRequest, type PermissionsResource, type Plan, type PollOptions, type Receipt, type Run, type RunCreateParams, type RunFile, type RunListParams, type RunOutcome, RunPausedError, RunStream, type RunStreamOptions, RunTimeoutError, type RunUsage, RunWaitAbortedError, type RunsResource, type SettingsResource, type SubscriptionBillingPeriod, type SubscriptionCheckout, type SubscriptionCheckoutParams, type SubscriptionPlanId, TERMINAL_STATUSES, type Task, type TaskCreateParams, type TaskListParams, type TaskRunParams, type TaskUpdateParams, type TasksResource, type Teammate, type TokenTransaction, type TopupParams, type Trigger, type TriggerCreateParams, type TriggerType, type TriggersResource, type Usage, type UsageBucket, type UsageModelSlice, type UsageTimeseries, type UsageTimeseriesParams, type UsageTotals, type UsersResource, type VerifySignatureOptions, type WaitOptions, type Webhook, type WebhookDelivery, type WebhookToggle, type WebhooksResource, createAccountResource, createBillingResource, createHttp, createMemoriesResource, createModelConnectionsResource, createModelsResource, createPermissionsResource, isPlanApproval, planText, pollRun, verifySignature, waitForRun };