@usethrottle/mcp 0.2.0 → 0.2.1

package/dist/lib.d.cts

@@ -14,6 +14,21 @@ interface RequestOptions {
      * `(workspace, application, environment, key, method, path)`.
      */
     idempotencyKey?: string;
+    /**
+     * Sent as `X-Throttle-Application-Id` on this one request only — see
+     * `PerCallOptions`.
+     */
+    applicationId?: string;
+}
+interface PerCallOptions {
+    /**
+     * Overrides which application a single `get`/`list` call reads from (the
+     * `oauth_token` auth branch validates this against the grant's own
+     * workspace membership; see `resolveOAuthApplication`). Scoped to this one
+     * request — never stored on the client instance — so concurrent calls with
+     * different application ids cannot bleed into each other.
+     */
+    applicationId?: string;
 }
 interface Pagination {
     cursor: string | null;
@@ -25,14 +40,26 @@ interface ListResult<T> {
 }
 type Fetcher = typeof fetch;
 declare class ThrottleClient {
-    private readonly auth;
+    private auth;
     private readonly fetchImpl;
     constructor(auth: AuthCtx, fetchImpl?: Fetcher);
+    /**
+     * Swap the credential every later request is sent with. The hosted remote
+     * server builds one client per MCP session at `initialize`, but an OAuth
+     * access token lives one hour and the MCP client refreshes it underneath
+     * the session — each request then arrives with a newer bearer than the one
+     * the session was opened with. Without this, the session keeps calling the
+     * REST API with the token it was born with and every tool fails with a 401
+     * the moment that first token expires, even though the caller is still
+     * perfectly authenticated.
+     */
+    setApiKey(apiKey: string): void;
     private requestJson;
     /** Unwraps the `{ data }` envelope. Key presence, not `??` — `{data: null}` unwraps to null. */
-    get<T>(path: string, query?: Record<string, unknown>): Promise<T>;
-    list<T>(path: string, query?: Record<string, unknown>): Promise<ListResult<T>>;
+    get<T>(path: string, query?: Record<string, unknown>, options?: PerCallOptions): Promise<T>;
+    list<T>(path: string, query?: Record<string, unknown>, options?: PerCallOptions): Promise<ListResult<T>>;
     post<T>(path: string, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, options?: RequestOptions): Promise<T>;
 }
 
 /**
@@ -67,7 +94,8 @@ interface ContractIndex {
 }
 
 /**
- * `search_docs`, answered from an index of `apps/docs` bundled at build time.
+ * `search_docs`, answered from an index of the docs pages in `apps/web`,
+ * bundled at build time.
  *
  * Scoring mirrors the CLI's proven approach: title hits beat heading hits, which
  * beat body hits, and an exact phrase beats scattered terms. Deliberately simple —
@@ -122,6 +150,22 @@ interface RegistrationPolicy {
     identity: Identity;
     allowWrites: boolean;
     allowLiveWrites: boolean;
+    /**
+     * Whether sandbox-only writes (`seed_test_data`) register without
+     * `allowWrites`. Defaults to true — the documented CLI behaviour, where
+     * seeding a non-production environment needs no flag. The hosted remote
+     * server passes false: it is published as strictly read-only, and a
+     * directory reviewer connecting with a non-production credential must not
+     * find a tool that creates customers and orders.
+     */
+    allowSandboxWrites?: boolean;
+    /**
+     * Whether `credentialScoped` actions (`api_get`) register. Defaults to true
+     * for the CLI. The hosted server passes false: on an OAuth surface every
+     * tool declares the scopes it asks consent for, and a tool that reads any
+     * path cannot.
+     */
+    allowCredentialScoped?: boolean;
 }
 /**
  * Which tools this session gets. Pure and exported so the policy is testable
@@ -156,6 +200,16 @@ interface CreateServerOptions extends RegistrationPolicy {
     client: ThrottleClient;
     contract: ContractIndex;
     docs: DocsIndex;
+    /**
+     * The `WWW-Authenticate` challenge value the hosting transport advertises
+     * (RFC 9728 `Bearer resource_metadata="..."`). When set, a tool call that
+     * fails because the REST API rejected the credential (HTTP 401 — an expired
+     * or revoked OAuth access token) carries it back as
+     * `_meta["mcp/www_authenticate"]`, which is what ChatGPT and other remote
+     * clients key their re-authorization UI on. The stdio CLI leaves it unset:
+     * its operator-provided key has no re-auth flow to trigger.
+     */
+    authChallenge?: string;
 }
 declare function createServer(options: CreateServerOptions): McpServer;
 

package/dist/lib.d.ts

@@ -14,6 +14,21 @@ interface RequestOptions {
      * `(workspace, application, environment, key, method, path)`.
      */
     idempotencyKey?: string;
+    /**
+     * Sent as `X-Throttle-Application-Id` on this one request only — see
+     * `PerCallOptions`.
+     */
+    applicationId?: string;
+}
+interface PerCallOptions {
+    /**
+     * Overrides which application a single `get`/`list` call reads from (the
+     * `oauth_token` auth branch validates this against the grant's own
+     * workspace membership; see `resolveOAuthApplication`). Scoped to this one
+     * request — never stored on the client instance — so concurrent calls with
+     * different application ids cannot bleed into each other.
+     */
+    applicationId?: string;
 }
 interface Pagination {
     cursor: string | null;
@@ -25,14 +40,26 @@ interface ListResult<T> {
 }
 type Fetcher = typeof fetch;
 declare class ThrottleClient {
-    private readonly auth;
+    private auth;
     private readonly fetchImpl;
     constructor(auth: AuthCtx, fetchImpl?: Fetcher);
+    /**
+     * Swap the credential every later request is sent with. The hosted remote
+     * server builds one client per MCP session at `initialize`, but an OAuth
+     * access token lives one hour and the MCP client refreshes it underneath
+     * the session — each request then arrives with a newer bearer than the one
+     * the session was opened with. Without this, the session keeps calling the
+     * REST API with the token it was born with and every tool fails with a 401
+     * the moment that first token expires, even though the caller is still
+     * perfectly authenticated.
+     */
+    setApiKey(apiKey: string): void;
     private requestJson;
     /** Unwraps the `{ data }` envelope. Key presence, not `??` — `{data: null}` unwraps to null. */
-    get<T>(path: string, query?: Record<string, unknown>): Promise<T>;
-    list<T>(path: string, query?: Record<string, unknown>): Promise<ListResult<T>>;
+    get<T>(path: string, query?: Record<string, unknown>, options?: PerCallOptions): Promise<T>;
+    list<T>(path: string, query?: Record<string, unknown>, options?: PerCallOptions): Promise<ListResult<T>>;
     post<T>(path: string, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, options?: RequestOptions): Promise<T>;
 }
 
 /**
@@ -67,7 +94,8 @@ interface ContractIndex {
 }
 
 /**
- * `search_docs`, answered from an index of `apps/docs` bundled at build time.
+ * `search_docs`, answered from an index of the docs pages in `apps/web`,
+ * bundled at build time.
  *
  * Scoring mirrors the CLI's proven approach: title hits beat heading hits, which
  * beat body hits, and an exact phrase beats scattered terms. Deliberately simple —
@@ -122,6 +150,22 @@ interface RegistrationPolicy {
     identity: Identity;
     allowWrites: boolean;
     allowLiveWrites: boolean;
+    /**
+     * Whether sandbox-only writes (`seed_test_data`) register without
+     * `allowWrites`. Defaults to true — the documented CLI behaviour, where
+     * seeding a non-production environment needs no flag. The hosted remote
+     * server passes false: it is published as strictly read-only, and a
+     * directory reviewer connecting with a non-production credential must not
+     * find a tool that creates customers and orders.
+     */
+    allowSandboxWrites?: boolean;
+    /**
+     * Whether `credentialScoped` actions (`api_get`) register. Defaults to true
+     * for the CLI. The hosted server passes false: on an OAuth surface every
+     * tool declares the scopes it asks consent for, and a tool that reads any
+     * path cannot.
+     */
+    allowCredentialScoped?: boolean;
 }
 /**
  * Which tools this session gets. Pure and exported so the policy is testable
@@ -156,6 +200,16 @@ interface CreateServerOptions extends RegistrationPolicy {
     client: ThrottleClient;
     contract: ContractIndex;
     docs: DocsIndex;
+    /**
+     * The `WWW-Authenticate` challenge value the hosting transport advertises
+     * (RFC 9728 `Bearer resource_metadata="..."`). When set, a tool call that
+     * fails because the REST API rejected the credential (HTTP 401 — an expired
+     * or revoked OAuth access token) carries it back as
+     * `_meta["mcp/www_authenticate"]`, which is what ChatGPT and other remote
+     * clients key their re-authorization UI on. The stdio CLI leaves it unset:
+     * its operator-provided key has no re-auth flow to trigger.
+     */
+    authChallenge?: string;
 }
 declare function createServer(options: CreateServerOptions): McpServer;