@alfe.ai/mcp-server 0.2.5 → 0.2.7

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { ChangelogEntry, EncryptedEnvelopeV1, FieldEnvelope, FieldFormat, FieldSensitivity, GeneratedDataKey, IntegrationConfigResult, IntegrationInstall, RegistryEntry, ScopeInfo, SecretAggregate, SecretCategory, SecretMetadata, SecretScope } from "@alfe/types";
 
 //#region ../agent-api-client/dist/index.d.ts
@@ -29,26 +30,32 @@ declare class AgentApiTransport {
    * `Content-Type: application/json` and parses a `{ data: T }` envelope,
    * neither of which fits a raw-audio flow (voice TTS/STT), so those go
    * through this instead. Auth (Bearer), the request budget, and the single
-   * retry on transient 5xx / network errors are kept in sync with
-   * `request()`. Retries fire only on statuses produced BEFORE the route
-   * handler runs (authorizer-timeout 500 + LB 502/503/504), so re-issuing a
-   * POST does not risk a duplicate side effect.
+   * retry policy on transient 5xx / network errors is kept in sync with
+   * `request()`. Safe read methods retry once by default; mutation methods do
+   * not, because a response can be lost after a handler or provider call has
+   * already succeeded.
    */
   rawRequest(path: string, init: {
     method: string;
     headers: Headers;
     body?: BodyInit | Uint8Array;
+  }, extra?: {
+    retry?: boolean;
   }): Promise<Response>;
   /**
    * @param extra.timeoutMs Per-request abort timeout (default REQUEST_TIMEOUT_MS).
    *   Long endpoints (image generation) pass a larger value so the gateway's
    *   own timeout wins with a readable status instead of a client-side abort.
-   * @param extra.retry Whether to retry once on transient failures (default
-   *   true). Expensive/non-idempotent endpoints pass false.
+   * @param extra.retry Whether to retry once on transient failures. Safe reads
+   *   (GET/HEAD/OPTIONS) default to true; mutations default to false. Set true
+   *   only when the endpoint's server-side contract is explicitly idempotent.
+   * @param extra.signal Optional caller cancellation combined with the client's
+   *   own timeout budget. Aborting either signal cancels the request.
    */
   request<T>(path: string, options?: RequestInit, extra?: {
     timeoutMs?: number;
     retry?: boolean;
+    signal?: AbortSignal;
   }): Promise<T>;
 }
 /**
@@ -64,7 +71,7 @@ declare class ApiBase {
 //# sourceMappingURL=transport.d.ts.map
 //#endregion
 //#region src/domains/workspace.d.ts
-/** Response of GET /agents/me/workspace (services/agents). */
+/** Response of GET /agent/workspace (services/agents). */
 interface AgentWorkspaceInfo {
   templateKey?: string;
   defaultModel?: string;
@@ -92,7 +99,7 @@ interface AgentWorkspaceInfo {
 }
 declare class WorkspaceApi extends ApiBase {
   /**
-   * GET /agents/me/workspace — workspace config for the authenticated agent
+   * GET /agent/workspace — workspace config for the authenticated agent
    * (template assignment, default model, org roster).
    */
   getWorkspace(): Promise<AgentWorkspaceInfo>;
@@ -235,6 +242,8 @@ declare class SyncApi extends ApiBase {
   sharedListFiles(args: {
     scope: "org" | "team" | "project";
     scopeId: string;
+    limit?: number;
+    cursor?: string;
   }): Promise<{
     files: SharedFileEntry[];
     nextCursor: string | null;
@@ -394,7 +403,9 @@ declare class KnowledgeApi extends ApiBase {
    * from `services/org`, then fetches the bytes directly from S3 (the one
    * legitimate raw fetch in a plugin — same pattern as sync).
    */
-  readScopeDoc(scopeType: KnowledgeScopeType, scopeId: string, filePath: string): Promise<{
+  readScopeDoc(scopeType: KnowledgeScopeType, scopeId: string, filePath: string, opts?: {
+    maxBytes?: number;
+  }): Promise<{
     filePath: string;
     text: string;
   }>;
@@ -433,15 +444,11 @@ interface MobileAvailableNumber {
 }
 /** Approved WhatsApp content template from GET /mobile/whatsapp/templates. */
 interface WhatsAppTemplate {
-  sid: string;
-  friendlyName: string;
+  contentSid: string;
+  name: string;
   language: string;
   body: string;
   variables: Record<string, string>;
-  dateCreated: string;
-  dateUpdated: string;
-  approvalStatus?: string;
-  rejectionReason?: string;
   category?: string;
 }
 declare class MobileApi extends ApiBase {
@@ -689,15 +696,22 @@ declare class SearchApi extends ApiBase {
     offset?: number;
     country?: string;
     freshness?: string;
+  }, options?: {
+    signal?: AbortSignal;
   }): Promise<unknown>;
   searchImages(params: {
     query: string;
     count?: number;
+  }, options?: {
+    signal?: AbortSignal;
   }): Promise<unknown>;
   searchNews(params: {
     query: string;
     count?: number;
+    offset?: number;
     freshness?: string;
+  }, options?: {
+    signal?: AbortSignal;
   }): Promise<unknown>;
   /** Search news across the selected provider's corpus. → POST /agent/news/search */
   newsSearch(params: {
@@ -721,6 +735,48 @@ declare class SearchApi extends ApiBase {
 }
 //# sourceMappingURL=search.d.ts.map
 //#endregion
+//#region src/domains/webhooks.d.ts
+interface AgentWebhook {
+  webhookId: string;
+  tenantId: string;
+  agentId: string;
+  name: string;
+  provider: string;
+  active: boolean;
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+}
+interface CreatedAgentWebhook extends AgentWebhook {
+  url: string;
+  signingSecret: string;
+}
+interface AgentWebhookDelivery {
+  deliveryId: string;
+  webhookId: string;
+  status: string;
+  attempts: number;
+  createdAt: string;
+  deliveredAt?: string;
+}
+declare class WebhooksApi extends ApiBase {
+  createWebhook(args: {
+    name: string;
+    provider?: "generic" | "github" | "stripe" | "slack";
+  }): Promise<CreatedAgentWebhook>;
+  listWebhooks(): Promise<AgentWebhook[]>;
+  deleteWebhook(webhookId: string): Promise<{
+    webhookId: string;
+    active: false;
+  }>;
+  rotateWebhookSecret(webhookId: string): Promise<{
+    webhookId: string;
+    signingSecret: string;
+  }>;
+  listWebhookDeliveries(webhookId: string): Promise<AgentWebhookDelivery[]>;
+}
+//# sourceMappingURL=webhooks.d.ts.map
+//#endregion
 //#region src/domains/chat.d.ts
 declare class ChatApi extends ApiBase {
   presignAttachments(files: {
@@ -857,8 +913,9 @@ declare class ConnectCredentialsApi extends ApiBase {
    * selector arg (e.g. `xeroTenantId`) on every credential-touching tool
    * and look up the matching account by that selector at dispatch time.
    *
-   * Returned `accounts[i].accountIdentifier` is the Xero tenantId — the
-   * stable cross-session identifier the LLM should pass.
+   * `xeroTenantId` is the model-facing organisation selector. The separate
+   * `accountIdentifier` is the Connect persistence key used for refresh and
+   * may be an email; never substitute one for the other.
    */
   getXeroAccounts(): Promise<{
     accounts: {
@@ -876,12 +933,12 @@ declare class ConnectCredentialsApi extends ApiBase {
     expiresAt: string;
   }>;
   /**
-   * Pattern A: refresh a specific Xero connection by its `accountIdentifier`
-   * (the Xero `tenantId`). The legacy `refreshXeroToken()` only refreshes
-   * the *primary* connection, which is wrong for multi-tenant Xero where
-   * each tenant has its own non-interchangeable access token.
+   * Refresh a specific Xero Connection by its exact `accountIdentifier` from
+   * `getXeroAccounts()`. Do not substitute `xeroTenantId`: current Xero OAuth
+   * rows may use the account email as their persistence key even when a sole
+   * organisation tenant ID is available in provider metadata.
    */
-  refreshXeroAccountToken(xeroTenantId: string): Promise<{
+  refreshXeroAccountToken(accountIdentifier: string): Promise<{
     accessToken: string;
     accessTokenExpiresAt: string;
     expiresAt: string;
@@ -1036,6 +1093,21 @@ declare class ConnectCredentialsApi extends ApiBase {
     accessToken: string;
     expiresAt: string;
   }>;
+  /**
+   * Pattern A: refresh one MYOB Connection by its stable
+   * `accountIdentifier` (the MYOB business id returned by
+   * `getMYOBAccounts()`).
+   *
+   * MYOB refresh tokens belong to individual Connection rows. A
+   * multi-business client must use this method instead of refreshing the
+   * primary Connection and copying that access token into every cached
+   * business client.
+   */
+  refreshMYOBAccountToken(accountIdentifier: string): Promise<{
+    accessToken: string;
+    accessTokenExpiresAt: string;
+    expiresAt: string;
+  }>;
   /**
    * @deprecated Returns a single primary credential blob. Use
    * `getSalesforceAccounts()` for the multi-account shape required by
@@ -1098,9 +1170,6 @@ declare class ConnectCredentialsApi extends ApiBase {
       connectedAt: string;
       accessToken: string;
       accessTokenExpiresAt: string;
-      refreshToken: string;
-      clientId: string;
-      clientSecret: string;
       email: string;
       microsoftTenantId: string;
       workspaceDomain: string;
@@ -1206,10 +1275,41 @@ declare class ConnectCredentialsApi extends ApiBase {
       brokerName?: string;
       accountNumber?: string;
       accessToken: string;
+      /**
+       * The stable per-grant Connection key (`ctid:<userId>`) this account
+       * belongs to. Every trading account under one cTrader login shares one
+       * grant (one OAuth token), so this is the identifier the MCP server
+       * passes to `refreshCTraderAccount()` to rotate the token for the whole
+       * grant on a `CH_ACCESS_TOKEN_INVALID` expiry. Empty string when the
+       * server did not supply one (legacy rows) — such an account can still
+       * trade with its current token but cannot self-refresh.
+       */
+      accountIdentifier: string;
     }[];
     clientId: string;
     clientSecret: string;
   }>;
+  /**
+   * Pattern A: refresh a specific cTrader grant by its stable
+   * `accountIdentifier` (`ctid:<userId>` from `getCTraderAccounts()`).
+   *
+   * cTrader access tokens live ~30 days; the `getCTraderAccounts()` /
+   * credentials reads serve the STORED token without refreshing, so refresh is
+   * the consumer's job. `@alfe.ai/ctrader-mcp` calls this when the cTrader Open
+   * API rejects an account-auth with `CH_ACCESS_TOKEN_INVALID`, then re-runs
+   * the socket handshake with the returned `accessToken`.
+   *
+   * Refreshing one grant rotates the single OAuth token that covers EVERY
+   * trading account under that login. cTrader's refresh token itself does not
+   * expire but may rotate on refresh (`rotatesRefreshToken: true`); connect
+   * persists the rotated refresh token server-side, so the caller only needs
+   * the new `accessToken`. Mirrors `refreshXeroAccountToken`.
+   */
+  refreshCTraderAccount(accountIdentifier: string): Promise<{
+    accessToken: string;
+    accessTokenExpiresAt: string;
+    expiresAt: string;
+  }>;
   /**
    * @deprecated Returns a single primary credential blob. Use
    * `getShopifyAccounts()` for the multi-account shape required by Pattern A
@@ -1374,59 +1474,35 @@ declare class IdentityApi extends ApiBase {
   }>;
   mergeIdentities(survivorId: string, args: {
     mergedId: string;
-    changedBy: {
-      type: string;
-      id: string;
-      name?: string;
-    };
   }): Promise<{
     ok: boolean;
     error?: string;
   }>;
-  unmergeIdentity(identityId: string, args: {
-    changedBy: {
-      type: string;
-      id: string;
-      name?: string;
-    };
-  }): Promise<{
+  unmergeIdentity(identityId: string): Promise<{
     ok: boolean;
     error?: string;
   }>;
   addIdentityNote(identityId: string, args: {
     content: string;
     category?: string;
-    changedBy: {
-      type: string;
-      id: string;
-      name?: string;
-    };
   }): Promise<{
     noteId: string | null;
   }>;
   tagIdentity(identityId: string, args: {
     tag: string;
     action: "add" | "remove";
-    changedBy: {
-      type: string;
-      id: string;
-      name?: string;
-    };
   }): Promise<{
     ok: boolean;
   }>;
   getIdentityChangelog(identityId: string, args?: {
     limit?: number;
+    cursor?: string;
   }): Promise<{
     entries: unknown[];
+    cursor: string | null;
   }>;
   rollbackIdentity(identityId: string, args: {
     targetVersion: number;
-    changedBy: {
-      type: string;
-      id: string;
-      name?: string;
-    };
   }): Promise<{
     ok: boolean;
     entry?: unknown;
@@ -1465,7 +1541,7 @@ declare class IdentityApi extends ApiBase {
     verified: boolean;
     identityId?: string;
     /** Phase 2: how the confirm resolved — Scenario A vs B. */
-    action?: "merged" | "contact_verified";
+    action?: "merged" | "contact_verified" | "already_confirmed";
     error?: string;
   }>;
   /**
@@ -1597,8 +1673,21 @@ declare class MemoryApi extends ApiBase {
     messageCount: number;
   }>;
   memoryLoadContext(tier?: number, topicHint?: string): Promise<{
+    tier: number;
+    facts: {
+      subject: string;
+      predicate: string;
+      object: string;
+      since: string;
+    }[];
+    memories: {
+      text: string;
+      topic: string;
+      subtopic: string;
+      score: number;
+    }[];
+    tokenEstimate: number;
     formatted: string;
-    [key: string]: unknown;
   }>;
   memoryLookupEntity(subject: string): Promise<{
     subject: string;
@@ -1830,7 +1919,7 @@ declare class TeamsApi extends ApiBase {
 
 //#endregion
 //#region src/index.d.ts
-interface AgentApiClient extends SyncApi, IntegrationsApi, WorkspaceApi, ConnectCredentialsApi, TeamsApi, ChatApi, SecretsApi, IdentityApi, MemoryApi, SearchApi, KnowledgeApi, DatabaseApi, MobileApi, RemoteApi, SelfApi, VoiceApi, ImagesApi {}
+interface AgentApiClient extends SyncApi, IntegrationsApi, WorkspaceApi, ConnectCredentialsApi, TeamsApi, ChatApi, SecretsApi, IdentityApi, MemoryApi, SearchApi, KnowledgeApi, DatabaseApi, MobileApi, RemoteApi, SelfApi, VoiceApi, ImagesApi, WebhooksApi {}
 declare class AgentApiClient extends ApiBase {
   constructor(config: AgentApiClientConfig);
 }
@@ -1881,8 +1970,8 @@ declare const SERVER_BIN_PATH: string;
 type ServerProfile = 'default' | 'claude-code';
 interface ServerOptions {
   /**
-   * Optional override for the API client — tests inject a fake so the
-   * server can be exercised end-to-end without real network I/O.
+   * Optional pre-bound API client. Must be supplied together with `apiUrl` so
+   * the client authority and the OAuth URL authority cannot diverge.
    */
   client?: AgentApiClient;
   /** Pre-resolved context fields. If omitted, the server calls `whoami()` itself. */
@@ -1890,7 +1979,7 @@ interface ServerOptions {
     agentId: string;
     tenantId: string;
   };
-  /** Override apiUrl reported in the ToolContext. Defaults to the resolved CLI config. */
+  /** Authority bound to an injected `client`. Omit both to use resolved CLI config. */
   apiUrl?: string;
   /**
    * Tool surface to register. Defaults to `default` (integrations only) so
@@ -1912,9 +2001,9 @@ interface ServerOptions {
  * Pure construction — does not connect a transport. Callers (the bin
  * entry, or tests) attach `StdioServerTransport` or any other transport.
  *
- * `resolveConfig()` is only called when neither `client` nor `apiUrl`
- * is provided — tests can fully construct the server without touching
- * `~/.alfe/config.toml`.
+ * `resolveConfig()` is only called when the main `client`/`apiUrl` pair is
+ * omitted. Tests and alternate hosts can inject a complete pair without
+ * touching `~/.alfe/config.toml`.
  */
 declare function createServer(opts?: ServerOptions): Promise<McpServer>;
 /**
@@ -1925,14 +2014,13 @@ declare function createServer(opts?: ServerOptions): Promise<McpServer>;
  */
 declare function parseProfileArg(argv: string[]): ServerProfile;
 /**
- * Entry point — boot the server on stdio. Used by `bin.ts`. Any
- * startup failure is fatal: log and exit non-zero so the bundler's
- * connection attempt surfaces a clear error rather than a hung
- * handshake.
+ * Boot the server and attach its transport. Used by `bin.ts`; tests can inject
+ * an in-memory transport. Process policy (logging, exit code, signals) remains
+ * in the executable boundary rather than this reusable library function.
  */
-declare function main(opts?: {
-  profile?: ServerProfile;
-}): Promise<void>;
+declare function main(opts?: ServerOptions & {
+  transport?: Transport;
+}): Promise<McpServer>;
 //# sourceMappingURL=index.d.ts.map
 
 //#endregion