@parall/sdk 1.52.0 → 1.52.2

package/src/types.ts

@@ -2878,7 +2878,7 @@ export interface InboxItem {
 // External IM Channel Types (platform-mediated Feishu/Slack channel)
 // ============================================================
 
-export type ChannelProvider = 'feishu' | 'slack';
+export type ChannelProvider = 'feishu' | 'slack' | 'wechat';
 export type ChannelConnectionStatus = 'pending' | 'active' | 'disabled';
 /**
  * Inbound transport for a connection. Defaults to the provider's lowest-
@@ -2913,6 +2913,9 @@ export interface ChannelConnection {
    * hides the upgrade CTA when this is false/absent.
    */
   upgrade_eligible?: boolean;
+  /** Set when the provider reported the device node offline (wechat Offline
+   *  event) — the connection stays active but needs a vendor-side re-login. */
+  last_offline_at?: string | null;
   created_at: string;
   updated_at: string;
 }
@@ -2926,6 +2929,8 @@ export interface ChannelCredentialsInput {
   /** Slack fields (webhook-only: the signing secret is the verifier). */
   bot_token?: string;
   signing_secret?: string;
+  /** WeChat field (research preview): vendor API credential. */
+  token?: string;
   team_id?: string;
 }
 
@@ -3063,8 +3068,9 @@ export interface SlackManifestLinkResult {
  * generic ChannelProvider here would compile call sites that always 400.
  */
 export interface SendChannelMessageInput {
-  channel_type: 'slack';
-  /** Vendor-native conversation id from the inbound event (e.g. C…/D…). */
+  channel_type: 'slack' | 'wechat';
+  /** Vendor-native conversation id from the inbound event (e.g. C…/D… for
+   *  slack, a wxid or room id for wechat). */
   conversation_id: string;
   /**
    * External message id being answered (channel-domain format:
@@ -3073,13 +3079,16 @@ export interface SendChannelMessageInput {
    * In DMs the SESSION never forks, but reply POSITION follows the
    * question: a thread-child id lands the reply inside that thread, a
    * bare id (or omitting the field) keeps the flattened main flow.
+   * WeChat has no threads — omit for wechat.
    */
   reply_to?: string;
+  /** WeChat-only: @-mention a group member (wxid) in a group reply. */
+  at?: string;
   text: string;
 }
 
 export interface SentChannelMessage {
-  channel_type: 'slack';
+  channel_type: 'slack' | 'wechat';
   conversation_id: string;
   /**
    * Channel-domain external id — `{channel}:{ts}` for top-level posts,
@@ -3112,6 +3121,13 @@ export interface SlackChannelsPage {
   next_cursor?: string;
 }
 
+/** WeChat address book (id lists only — the vendor returns no names). */
+export interface WechatContactsPage {
+  friends: string[];
+  chatrooms: string[];
+  ghs: string[];
+}
+
 export interface SlackUserInfo {
   id: string;
   name: string;
@@ -3453,10 +3469,11 @@ export interface DispatchReceivedData {
 /**
  * Terminal counterpart of DispatchReceivedData: published on org:{orgId} when
  * a message WorkItem reaches a terminal resolution, so the message-level
- * Activity indicator flips active→done — or, per indicator v2.1, active→failed
- * for `redrive_exhausted` (persistent dead-letter row); only `cancelled`
- * clears the indicator — without inferring completion from agent session
- * state. Message WorkItems only.
+ * Activity state flips active→done — or, per indicator v2.1, active→failed
+ * for `redrive_exhausted`. Failed history remains available through Activity;
+ * only a live event produces the transient inline failure indicator. Only
+ * `cancelled` clears the activity — without inferring completion from agent
+ * session state. Message WorkItems only.
  */
 export interface DispatchResolvedData {
   agent_id: string;
@@ -4510,32 +4527,6 @@ export interface MachineClip {
   browser_profile_id?: string | null;
 }
 
-// Pinix registry catalog clip info (from GET /clip/v1/registry/clips,
-// which proxies the public Pinix registry GET /search).
-export interface RegistryCommandInfo {
-  name: string;
-  description: string;
-  input?: string;
-  output?: string;
-}
-
-export interface RegistryDependencyInfo {
-  package: string;
-  version: string;
-}
-
-export interface RegistryClipInfo {
-  name: string; // @scope/name (canonical package id)
-  package: string; // @scope/name (alias derivation + install source_ref)
-  version: string;
-  type: string; // registry package type (e.g. "clip")
-  description?: string;
-  domain?: string;
-  author?: string;
-  commands: RegistryCommandInfo[];
-  dependencies: Record<string, RegistryDependencyInfo>;
-}
-
 // Clip WS event data types
 export type ClipCreatedData = Clip;
 export type ClipUpdatedData = Clip;
@@ -4749,9 +4740,66 @@ export interface ClipConnection {
   updated_at: string;
 }
 
-/** v1 MCP clip auth modes. Server-side OAuth is a designed follow-up. */
+/**
+ * MCP clip auth modes this SDK can WRITE: the pre-shared credential kinds a
+ * `PUT …/mcp-config` may set. Deliberately excludes `oauth` — an OAuth
+ * connection is created by the server-brokered browser flow (PUT → authorize
+ * URL → public callback), which returns a different response shape and is
+ * typed separately (MCPOAuthInitiateRequest/Response). Widening this union
+ * would make `putClipMCPConfig({auth_type: 'oauth'})` type-legal while its
+ * declared return type is wrong. Reads use MCPConfigAuthType.
+ */
 export type MCPAuthType = 'none' | 'bearer' | 'api_key';
 
+/**
+ * MCP clip auth modes a config can REPORT. A config authorized through the
+ * OAuth flow reads back as `oauth`, so every reader must handle it even
+ * though no typed call here produces one.
+ */
+export type MCPConfigAuthType = MCPAuthType | 'oauth';
+
+/**
+ * Connection state of an `oauth` config (server-derived, deployment-instance
+ * fenced): `connected` = a valid or lazily-refreshable token; `needs_reauth` =
+ * an org admin must authorize again; `disconnected` = no authorization here.
+ */
+export type MCPOAuthStatus = 'connected' | 'needs_reauth' | 'disconnected';
+
+/**
+ * Body of the OAuth-initiating `PUT …/mcp-config`: `auth_type` is the literal
+ * `'oauth'` and there is no credential field — the authorization happens in
+ * the provider's browser flow. Kept apart from MCPConfigPutRequest because
+ * the response is MCPOAuthInitiateResponse, not MCPConfigResponse (see the
+ * MCPAuthType note).
+ */
+export interface MCPOAuthInitiateRequest {
+  server_url: string;
+  auth_type: 'oauth';
+}
+
+/**
+ * Response of an OAuth-initiating PUT. Nothing is committed yet: an org
+ * admin's browser must complete `authorize_url` before `expires_at`; the
+ * config (and its default connection) is committed by the public callback. A
+ * repeat PUT while the attempt is live returns the SAME attempt's URL.
+ */
+export interface MCPOAuthInitiateResponse {
+  authorize_url: string;
+  expires_at: string;
+}
+
+/**
+ * Response of `POST …/mcp-config/oauth/disconnect` (If-Match mandatory).
+ * `revoked: false` means the provider-side grant may still exist and can need
+ * manual removal at the provider — the local disconnect stands regardless;
+ * `auth_type` remains `oauth` with `oauth_status: 'disconnected'`.
+ */
+export interface MCPOAuthDisconnectResponse {
+  disconnected: boolean;
+  revoked: boolean;
+  version: string;
+}
+
 /**
  * One tool from the cached tools/list snapshot. The full remote tool object is
  * snapshotted verbatim (inputSchema etc. ride along in the index signature).
@@ -4773,12 +4821,14 @@ export interface MCPToolInfo {
  */
 export interface MCPConfigResponse {
   server_url: string;
-  auth_type: MCPAuthType;
+  auth_type: MCPConfigAuthType;
   /** Whether a credential is stored (write-only; the value is never returned). */
   credential_set: boolean;
   /** Cached tools/list snapshot; untrusted remote metadata (see MCPToolInfo). */
   tools?: MCPToolInfo[];
   tools_refreshed_at?: string;
+  /** Present only when `auth_type` is `oauth`. */
+  oauth_status?: MCPOAuthStatus;
   /**
    * Opaque CAS token for If-Match on PUT/DELETE (lost-update protection).
    * Version mismatch answers `409 MCP_CONFIG_STALE`.
@@ -4801,9 +4851,7 @@ export interface MCPConfigPutRequest {
 
 /**
  * A clip in the api-server org registry (`crg_…`, table `clip_registry`) — the
- * v3 registry that install and clip connections operate on. Distinct from
- * {@link RegistryClipInfo}, which is the clip-service → Pinix Hub catalog proxy
- * and carries no registry id.
+ * v3 registry that publish, install, and clip connections operate on.
  */
 export interface ClipRegistryEntry {
   id: string;
@@ -4830,6 +4878,45 @@ export interface InstallRegistryClipResponse {
   name: string;
 }
 
+/**
+ * Create or update a clip in the org registry
+ * (`POST /orgs/{orgId}/clip-registry/publish`). Upsert is keyed by `name`
+ * within the org; updating an existing clip is author-only (`403 FORBIDDEN`
+ * otherwise). `files` REPLACES the clip's whole file set. An invalid
+ * `visibility` silently falls back to `private` server-side; `public` submits
+ * a pending review snapshot — cross-org installs keep serving the previously
+ * approved version until platform review approves it, while the publishing
+ * org itself always execs the latest working copy.
+ */
+export interface PublishRegistryClipRequest {
+  name: string;
+  description?: string;
+  visibility?: 'public' | 'private';
+  version?: string;
+  /** clip.json-shaped manifest (commands map + metadata). */
+  manifest?: Record<string, unknown>;
+  /** filename → UTF-8 content (e.g. `search.js`). */
+  files: Record<string, string>;
+}
+
+/**
+ * A clip's per-org agent exec access (`GET/PUT /orgs/{orgId}/clips/{clipId}/exec-access`).
+ *
+ * - `all_agents` (default): every org agent may exec the clip.
+ * - `selected_agents`: only the agents in `agent_ids` may exec; an empty list
+ *   blocks every agent. Denied agents also stop seeing the clip in
+ *   `clips/installed`, and exec answers `403 CLIP_AGENT_NOT_ALLOWED`.
+ *
+ * Decided by the CALLING org (an installer restricts its own agents, never the
+ * publisher's). Humans are never restricted; the PUT is human-only (an agent
+ * principal is refused so it can never widen its own access).
+ */
+export interface ClipAgentExecAccess {
+  mode: 'all_agents' | 'selected_agents';
+  /** Granted agent user ids under `selected_agents`; always [] under `all_agents`. */
+  agent_ids: string[];
+}
+
 /**
  * Execute a registry (Edge) clip command on an Edge device
  * (`POST /orgs/{orgId}/edge/exec`).