@rayrun/sdk 0.5.0 → 0.6.0

package/README.md

@@ -15,8 +15,8 @@ const { items: matchingTools } = await rayrun.tools.list({ query: 'create issue'
 Create keys in **Dashboard → Settings → API keys**. The plaintext is shown once.
 
 The client covers catalog search, connection and credential setup, OAuth links, indexing, tool and
-client policies, reusable access profiles, activity, review queues, and webhooks. Safe reads retry
-rate limits, server errors, and transient network failures; writes do not retry automatically.
+client policies, access profiles, Workspace Skills, Activity, review queues, and webhooks. Safe
+reads retry transient failures; writes do not retry automatically.
 
 Inspect the effective policy applied to one connected client without reproducing policy logic in
 your application:
@@ -38,17 +38,66 @@ const { profile } = await rayrun.accessProfiles.create({
   description: 'Read by default; sensitive tools stay blocked.',
 });
 
-await rayrun.accessProfiles.setPolicy(profile.uid, 'read-only', profile.toolPolicyVersion);
-await rayrun.accessProfiles.update(profile.uid, {
-  description: 'Read by default; sensitive tools stay blocked.',
-  expectedVersion: profile.toolPolicyVersion + 1,
+const policy = await rayrun.accessProfiles.setPolicy(
+  profile.uid,
+  'read-only',
+  profile.toolPolicyVersion,
+);
+const details = await rayrun.accessProfiles.update(profile.uid, {
+  description: 'Read-only support access; sensitive tools stay blocked.',
+  expectedVersion: policy.toolPolicyVersion,
   name: 'Support agents',
 });
 await rayrun.clients.setAccessProfile(clientUid, profile.uid, clientToolPolicyVersion);
+
+const profileHistory = await rayrun.accessProfiles.listConfigurationVersions(profile.uid);
+const original = await rayrun.accessProfiles.getConfigurationVersion(
+  profile.uid,
+  profileHistory.items.at(-1).uid,
+);
+await rayrun.accessProfiles.restoreConfigurationVersion(profile.uid, original.version.uid, {
+  expectedVersion: details.toolPolicyVersion,
+  reason: 'Restore the reviewed access ceiling',
+  riskConfirmed: true,
+});
 ```
 
 The effective policy is always the intersection of the workspace, profile, and client rules. A
-profile can narrow access but cannot grant something blocked by the workspace or client.
+profile can narrow access but cannot grant something blocked by the workspace or client. History
+versions profile details and rules together; assignments and archival stay outside the snapshot.
+Restore refuses missing tools and requires `riskConfirmed` when it would allow a Destructive or
+Unknown tool. Profile history is limited to 64 MiB per workspace.
+
+## Manage connection configuration history
+
+Connection names, slugs, descriptions, timeouts, enablement, and payload-capture preferences are
+saved as one immutable configuration snapshot. Credentials, headers, OAuth state, identity and tool
+policy, health, and index state are deliberately excluded.
+
+```js
+const { items: connections } = await rayrun.connections.list();
+const connection = connections[0];
+
+const updated = await rayrun.connections.setEnabled(connection.uid, {
+  enabled: false,
+  expectedVersion: connection.configurationVersion,
+});
+
+const history = await rayrun.connections.listConfigurationVersions(connection.uid, { limit: 25 });
+const selected = await rayrun.connections.getConfigurationVersion(
+  connection.uid,
+  history.items.at(-1).uid,
+);
+
+await rayrun.connections.restoreConfigurationVersion(connection.uid, selected.version.uid, {
+  expectedVersion: updated.connection.configurationVersion,
+  reason: 'Restore the reviewed service configuration',
+});
+```
+
+Every material update records the user or API key, channel, time, and optional reason. Identical
+saves are no-ops. Restore creates a new attributed version and fails with `version_conflict` if the
+connection changed after it was read.
 
 ## Manage hosted tool hooks
 
@@ -69,14 +118,22 @@ const saved = await rayrun.hooks.saveDraft(connectionUid, toolUid, {
   source: hook.draftSource,
   config: hook.draftConfig,
   expectedVersion: hook.version,
+  reason: 'Normalize upstream release results',
 });
 
-await rayrun.hooks.deploy(connectionUid, toolUid, {
+const deployed = await rayrun.hooks.deploy(connectionUid, toolUid, {
   expectedVersion: saved.hook.version,
   mode: 'shadow',
 });
 
 const runs = await rayrun.hooks.listRuns(connectionUid, toolUid, { limit: 25 });
+
+const history = await rayrun.hooks.listDraftVersions(connectionUid, toolUid, { limit: 25 });
+const prior = await rayrun.hooks.getDraftVersion(connectionUid, toolUid, history.items.at(-1).uid);
+await rayrun.hooks.restoreDraft(connectionUid, toolUid, prior.version.uid, {
+  expectedVersion: deployed.hook.version,
+  reason: 'Restore the previous argument mapping',
+});
 ```
 
 `setDeployment` moves an active or shadow pointer to an existing compatible revision, or deactivates
@@ -86,6 +143,56 @@ inspect source, generated declarations, revision history, and deployed-run metad
 and errors require `hooks:write`. `RayrunApiError.diagnostics` carries compiler line and column
 details for editor and CI output.
 
+Draft history is immutable and separate from deployment revisions: every material save records the
+API key or user, optional change note, source, and non-secret config. Re-saving identical content is
+a no-op. Restore always creates a new attributed draft head; it never rewrites the selected version.
+Source plus config history is limited to 64 MiB per workspace. Export required versions, then call
+`hooks.reset` with the current hook UID and version to permanently remove that hook's draft history
+and deployment revisions. Rayrun blocks connection deletion while hook history remains.
+
+## Publish Workspace Skills
+
+Encode each file as a package-relative path and base64 content. Validate before creating when CI
+needs the parsed name, frontmatter, digests, and warnings before it mutates workspace state.
+
+```js
+const files = [
+  {
+    path: 'SKILL.md',
+    contentBase64: Buffer.from(
+      `---
+name: incident-response
+description: Investigate and communicate production incidents.
+---
+
+# Incident response
+`,
+    ).toString('base64'),
+  },
+];
+
+const validation = await rayrun.skills.validate(files);
+const created = await rayrun.skills.create({ files, source: 'api' });
+
+await rayrun.skills.publish(created.skillUid, {
+  deliveryMode: 'both',
+  expectedVersion: created.configurationVersion,
+  profileUids: [],
+  riskConfirmed: validation.riskFlags.length > 0,
+});
+```
+
+`saveDraft` creates an immutable revision without changing the published pointer. `updateAudience`
+changes Code/Direct delivery and access-profile targeting without republishing. `setEnabled`,
+`archive`, `export`, `exportVersion`, and `restoreVersion` cover the reversible lifecycle;
+`delete` permanently removes retained revisions and delivery summaries after name and version
+confirmation. The name remains reserved.
+
+Use `skills:read` for inspection and export and add `skills:write` deliberately for publication
+automation. The ordinary workspace-management key preset excludes `skills:write`. Rayrun stores
+Skill bytes encrypted under the workspace key and serves them only after reauthorizing the MCP
+client on each read. `allowed-tools` is guidance, not access policy.
+
 ## Stream code run-ahead
 
 A model harness that receives `execute_code` arguments incrementally can let Rayrun start eligible
@@ -119,13 +226,47 @@ try {
 `open()` returns `null` when this optional optimization is rate-limited or temporarily unavailable.
 `feedArguments()` coalesces snapshots while one request is in flight; call `flush()` once before the
 final MCP request. It throws synchronously when a snapshot is not a string, so TypeScript users get
-the mistake at the call site. If an active session becomes unavailable, `meta` becomes an empty object. In
-either case, send the final MCP call normally. Rayrun only runs ahead tools that are explicitly
-allowed, approved as Read by a workspace owner, and advertised by their server as read-only and
-idempotent. The final MCP call rechecks the token, complete program, policy, definition, arguments,
-and upstream identity before it can use an early result.
+the mistake at the call site. If a session becomes unavailable, send the final MCP call normally.
+Rayrun runs ahead only allowed tools approved as Read and advertised as read-only and idempotent.
+The final call rechecks identity, policy, definition, arguments, and program before using an early
+result.
+
+## Manage webhook configuration history
+
+Webhook destination, description, event selection, delivery mode, batch size, enablement, and
+payload forwarding are saved together as immutable configuration versions. Signing secrets,
+delivery attempts, retry state, and health stay outside the snapshot.
+
+```js
+const { items: webhooks } = await rayrun.webhooks.list();
+const webhook = webhooks[0];
+
+const updated = await rayrun.webhooks.update(webhook.uid, {
+  enabled: false,
+  expectedVersion: webhook.configurationVersion,
+  reason: 'Pause deliveries during maintenance',
+});
+
+const history = await rayrun.webhooks.listConfigurationVersions(webhook.uid, { limit: 25 });
+const selected = await rayrun.webhooks.getConfigurationVersion(
+  webhook.uid,
+  history.items.at(-1).uid,
+);
+
+await rayrun.webhooks.restoreConfigurationVersion(webhook.uid, selected.version.uid, {
+  expectedVersion: updated.configurationVersion,
+  reason: 'Restore the reviewed destination',
+});
+```
+
+Every material update records the user or API key, channel, time, and optional reason. Restore
+creates a new version, revalidates the historical destination URL, and preserves the endpoint’s
+current signing secret and delivery state. Identical saves are no-ops, stale expected versions fail,
+and immutable webhook configuration history is limited to 64 MiB per workspace. Destination paths
+and query strings can contain provider tokens, so read-only keys receive `null` URLs; keys with
+`webhooks:write` receive the full current and historical destination.
 
-## Verify webhooks
+## Verify webhook signatures
 
 Pass the exact request body and the `Rayrun-Signature` header before parsing the event. Verification
 also rejects timestamps outside a five-minute replay window by default.

package/index.d.ts

@@ -12,10 +12,38 @@ export type ToolDecision = 'allow' | 'ask' | 'block';
 export type ToolAccessMode = 'read-only' | 'ask-before-changes' | 'allow-all' | 'custom';
 export type AccessProfileMode = 'read-only' | 'ask-before-changes' | 'allow-all' | 'block-all';
 export type Risk = 'read' | 'change' | 'destructive' | 'unknown';
+export type ConfigurationVersionSummary = {
+  actor: { name: string; type: 'api-key' | 'system' | 'user'; uid: string };
+  changeReason: string | null;
+  changeType: 'restore' | 'save';
+  channel: 'api' | 'browser' | 'legacy';
+  createdAt: string;
+  isCurrent: boolean;
+  restoredFromVersionUid: string | null;
+  revisionNumber: number;
+  uid: string;
+};
+export type ConnectionConfiguration = {
+  captureToolPayloads: boolean;
+  description: string | null;
+  displayName: string;
+  enabled: boolean;
+  requestTimeoutMs: number;
+  slug: string;
+};
+export type ConnectionConfigurationVersion = ConfigurationVersionSummary & {
+  previous: {
+    revisionNumber: number;
+    snapshot: ConnectionConfiguration;
+    uid: string;
+  } | null;
+  snapshot: ConnectionConfiguration;
+};
 export type Connection = {
   authorizedAt: string | null;
   authType: 'api-key' | 'basic' | 'none' | 'oauth2';
   createdAt: string;
+  configurationVersion: number;
   uid: string;
   displayName: string;
   enabled: boolean;
@@ -69,6 +97,7 @@ export type ToolHookRevision = {
 export type ToolHook = {
   activeRevisionStale: boolean;
   activeRevisionUid: string | null;
+  currentDraftRevisionNumber: number;
   draftConfig: Record<string, JsonValue>;
   draftSource: string;
   hookUid: string | null;
@@ -76,6 +105,7 @@ export type ToolHook = {
   shadowRevisionStale: boolean;
   shadowRevisionUid: string | null;
   target: {
+    available: boolean;
     definitionHash: string | null;
     inputSchema: Record<string, unknown>;
     name: string;
@@ -85,6 +115,31 @@ export type ToolHook = {
   types: string;
   version: number;
 };
+export type ToolHookDraftVersionSummary = {
+  actor: {
+    name: string;
+    type: 'api-key' | 'user';
+    uid: string;
+  };
+  changeReason: string | null;
+  changeType: 'restore' | 'save';
+  channel: 'api' | 'browser' | 'legacy';
+  createdAt: string;
+  isCurrent: boolean;
+  restoredFromVersionUid: string | null;
+  revisionNumber: number;
+  uid: string;
+};
+export type ToolHookDraftVersion = ToolHookDraftVersionSummary & {
+  config: Record<string, JsonValue>;
+  previous: {
+    config: Record<string, JsonValue>;
+    revisionNumber: number;
+    source: string;
+    uid: string;
+  } | null;
+  source: string;
+};
 export type ToolHookLogEntry = {
   data?: JsonValue;
   level: 'debug' | 'error' | 'info' | 'warn';
@@ -169,6 +224,7 @@ export type ClientTool = {
 };
 export type AccessProfile = {
   assignedClientCount: number;
+  assignedSkillCount: number;
   description: string;
   name: string;
   toolAccessMode: AccessProfileMode;
@@ -183,6 +239,24 @@ export type AccessProfileTool = {
   serviceName: string;
   uid: string;
 };
+export type AccessProfileConfiguration = {
+  description: string;
+  name: string;
+  toolAccessMode: AccessProfileMode;
+  toolRules: Array<{
+    connectionUid: string;
+    decision: ToolDecision;
+    toolUid: string;
+  }>;
+};
+export type AccessProfileConfigurationVersion = ConfigurationVersionSummary & {
+  previous: {
+    revisionNumber: number;
+    snapshot: AccessProfileConfiguration;
+    uid: string;
+  } | null;
+  snapshot: AccessProfileConfiguration;
+};
 export type Activity = {
   calledAt: string;
   clientName: string | null;
@@ -203,15 +277,109 @@ export type Review = {
   toolName: string;
   uid: string;
 };
-export type Webhook = {
+export type SkillFileInput = { contentBase64: string; path: string };
+export type SkillRiskFlag = 'binary-files' | 'possible-secrets' | 'scripts';
+export type SkillDeliveryMode = 'both' | 'code' | 'direct';
+export type Skill = {
+  archivedAt: string | null;
+  byteCount: number;
+  configurationVersion: number;
+  createdAt: string;
+  currentDraftRevisionNumber: number;
+  currentDraftVersionUid: string;
+  deliveryMode: SkillDeliveryMode;
+  description: string;
+  enabled: boolean;
+  fetchCount: number;
+  fileCount: number;
+  frontmatter: Record<string, JsonValue>;
+  lastFetchedAt: string | null;
+  name: string;
+  profiles: Array<{ name: string; uid: string }>;
+  publishedRevisionNumber: number | null;
+  publishedVersionUid: string | null;
+  riskFlags: SkillRiskFlag[];
+  state: 'archived' | 'disabled' | 'draft' | 'published';
+  uid: string;
+  updatedAt: string;
+  uri: string;
+};
+export type SkillVersion = {
+  actorName: string;
+  actorType: 'api-key' | 'user';
+  actorUid: string;
+  byteCount: number;
+  changeReason: string | null;
   createdAt: string;
+  fileCount: number;
+  isCurrentDraft: boolean;
+  isPublished: boolean;
+  restoredFromVersionUid: string | null;
+  revisionNumber: number;
+  riskFlags: SkillRiskFlag[];
+  source: 'api' | 'cli' | 'dashboard-folder' | 'dashboard-zip' | 'restore';
+  uid: string;
+};
+export type SkillDetail = {
+  deliveries: Array<{
+    clientName: string;
+    fetchCount: number;
+    firstFetchedAt: string;
+    lastFetchedAt: string;
+    method: 'resources/directory/read' | 'resources/read' | 'skills/get';
+    resourceUri: string;
+    userName: string | null;
+    versionUid: string;
+  }>;
+  files: Array<{ digest: string; mimeType: string; path: string; size: number; uri: string }>;
+  skill: Skill;
+  versions: SkillVersion[];
+};
+export type SkillMutationResult = {
+  configurationVersion: number;
+  skillUid: string;
+  unchanged: boolean;
+  versionUid: string | null;
+};
+export type SkillValidationResult = {
+  byteCount: number;
+  fileCount: number;
+  frontmatter: Record<string, JsonValue>;
+  manifestDigest: string;
+  name: string;
+  riskFlags: SkillRiskFlag[];
+};
+export type WebhookConfiguration = {
+  batchMaxEvents: number;
+  deliveryMode: 'batch' | 'single';
   description: string | null;
   enabled: boolean;
   eventTypes: WebhookEvent[];
   forwardToolPayloads: boolean;
-  uid: string;
   url: string;
 };
+export type WebhookConfigurationVersion = ConfigurationVersionSummary & {
+  previous: {
+    revisionNumber: number;
+    snapshot: WebhookConfigurationHistorySnapshot;
+    uid: string;
+  } | null;
+  snapshot: WebhookConfigurationHistorySnapshot;
+};
+export type WebhookConfigurationHistorySnapshot = Omit<WebhookConfiguration, 'url'> & {
+  url: string | null;
+};
+export type Webhook = Omit<WebhookConfiguration, 'url'> & {
+  configurationVersion: number;
+  createdAt: string;
+  health: 'delayed' | 'failing' | 'healthy' | 'idle' | 'pending';
+  lastDeliveredAt: string | null;
+  lastFailedAt: string | null;
+  oldestPendingAt: string | null;
+  pendingDeliveryCount: number;
+  uid: string;
+  url: string | null;
+};
 export type Credential =
   | {
       authType: 'api-key';
@@ -233,6 +401,7 @@ export type WebhookEvent =
   | 'connection.changed'
   | 'connection.indexed'
   | 'review.changed'
+  | 'skill.changed'
   | 'tool.definition-changed'
   | 'tool.policy-changed';
 export type WebhookDeliveryEvent = Exclude<WebhookEvent, '*'> | 'webhook.test';
@@ -305,6 +474,28 @@ export type WebhookPayload =
         toolUid: string;
       }
     >
+  | WebhookEnvelope<
+      'skill.changed',
+      {
+        deliveryMode?: SkillDeliveryMode;
+        eventType:
+          | 'skill-archived'
+          | 'skill-audience-changed'
+          | 'skill-deleted'
+          | 'skill-disabled'
+          | 'skill-draft-created'
+          | 'skill-enabled'
+          | 'skill-published'
+          | 'skill-restored';
+        eventUid: string;
+        name?: string;
+        profileUids?: string[];
+        restoredFromVersionUid?: string;
+        revisionNumber?: number;
+        skillUid: string;
+        versionUid?: string;
+      }
+    >
   | WebhookEnvelope<
       'tool.definition-changed',
       { approved: boolean; connectionUid: string; kind: 'added' | 'changed'; toolUid: string }
@@ -357,14 +548,39 @@ export class Rayrun {
         | { kind: 'openapi'; specificationUrl: string; baseUrl?: string; name?: string },
     ): Promise<{ connection: { uid: string } }>;
     createOAuthLink(uid: string): Promise<{ authorizationUrl: string }>;
-    delete(uid: string, expectedVersion: number): Promise<void>;
+    delete(uid: string): Promise<void>;
     index(uid: string): Promise<{ enqueued: boolean }>;
     list(query?: PageQuery): Promise<CursorPage<Connection>>;
+    getConfigurationVersion(
+      uid: string,
+      versionUid: string,
+    ): Promise<{ version: ConnectionConfigurationVersion }>;
+    listConfigurationVersions(
+      uid: string,
+      query?: PageQuery,
+    ): Promise<CursorPage<ConfigurationVersionSummary>>;
+    restoreConfigurationVersion(
+      uid: string,
+      versionUid: string,
+      body: { expectedVersion: number; reason?: string },
+    ): Promise<{
+      configuration: ConnectionConfiguration;
+      configurationVersion: number;
+      versionUid: string;
+    }>;
     setCredential(uid: string, body: Credential): Promise<{ enqueued: boolean }>;
     setEnabled(
       uid: string,
       enabled: boolean,
-    ): Promise<{ connection: Pick<Connection, 'displayName' | 'enabled' | 'uid'> }>;
+    ): Promise<{
+      connection: Pick<Connection, 'configurationVersion' | 'displayName' | 'enabled' | 'uid'>;
+    }>;
+    setEnabled(
+      uid: string,
+      body: { enabled: boolean; expectedVersion?: number },
+    ): Promise<{
+      connection: Pick<Connection, 'configurationVersion' | 'displayName' | 'enabled' | 'uid'>;
+    }>;
     setPolicy(uid: string, mode: ToolAccessMode): Promise<void>;
   };
   tools: {
@@ -382,20 +598,49 @@ export class Rayrun {
       body: { expectedVersion: number; mode: 'active' | 'shadow' },
     ): Promise<{ hook: ToolHook }>;
     get(connectionUid: string, toolUid: string): Promise<{ hook: ToolHook }>;
+    getDraftVersion(
+      connectionUid: string,
+      toolUid: string,
+      versionUid: string,
+    ): Promise<{ version: ToolHookDraftVersion }>;
+    listDraftVersions(
+      connectionUid: string,
+      toolUid: string,
+      query?: PageQuery,
+    ): Promise<CursorPage<ToolHookDraftVersionSummary>>;
     listRuns(
       connectionUid: string,
       toolUid: string,
       query?: PageQuery,
     ): Promise<CursorPage<ToolHookRun>>;
+    reset(
+      connectionUid: string,
+      toolUid: string,
+      body: { confirmationHookUid: string; expectedVersion: number; reason: string },
+    ): Promise<void>;
     saveDraft(
       connectionUid: string,
       toolUid: string,
       body: {
         config?: Record<string, JsonValue>;
         expectedVersion: number;
+        reason?: string;
         source: string;
       },
-    ): Promise<{ hook: ToolHook }>;
+    ): Promise<{
+      draftVersion: { revisionNumber: number; uid: string; unchanged: boolean };
+      hook: ToolHook;
+    }>;
+    restoreDraft(
+      connectionUid: string,
+      toolUid: string,
+      versionUid: string,
+      body: { expectedVersion: number; reason?: string },
+    ): Promise<{
+      draftVersion: { revisionNumber: number; uid: string };
+      hook: ToolHook;
+      restoredVersionUid: string;
+    }>;
     setDeployment(
       connectionUid: string,
       toolUid: string,
@@ -438,37 +683,149 @@ export class Rayrun {
   };
   accessProfiles: {
     archive(uid: string, expectedVersion: number): Promise<void>;
-    create(body: { description: string; name: string }): Promise<{ profile: AccessProfile }>;
+    create(body: {
+      description: string;
+      name: string;
+      reason?: string;
+    }): Promise<{ profile: AccessProfile }>;
     /** @deprecated Use archive. */
     delete(uid: string, expectedVersion: number): Promise<void>;
+    getConfigurationVersion(
+      uid: string,
+      versionUid: string,
+    ): Promise<{ version: AccessProfileConfigurationVersion }>;
     list(query?: PageQuery): Promise<CursorPage<AccessProfile>>;
+    listConfigurationVersions(
+      uid: string,
+      query?: PageQuery,
+    ): Promise<CursorPage<ConfigurationVersionSummary>>;
     listTools(uid: string, query?: PageQuery): Promise<CursorPage<AccessProfileTool>>;
-    setPolicy(uid: string, mode: AccessProfileMode, expectedVersion: number): Promise<void>;
+    restoreConfigurationVersion(
+      uid: string,
+      versionUid: string,
+      body: { expectedVersion: number; reason?: string; riskConfirmed?: boolean },
+    ): Promise<{
+      configuration: AccessProfileConfiguration;
+      toolPolicyVersion: number;
+      versionUid: string;
+    }>;
+    setPolicy(
+      uid: string,
+      mode: AccessProfileMode,
+      expectedVersion: number,
+      reason?: string,
+    ): Promise<{ toolPolicyVersion: number; unchanged: boolean }>;
     setToolPolicy(
       uid: string,
       toolUid: string,
       body: {
         decision: ToolDecision | null;
         expectedVersion: number;
+        reason?: string;
         riskConfirmed?: boolean;
       },
-    ): Promise<void>;
+    ): Promise<{ toolPolicyVersion: number; unchanged: boolean }>;
     update(
       uid: string,
-      body: { description: string; expectedVersion: number; name: string },
-    ): Promise<void>;
+      body: { description: string; expectedVersion: number; name: string; reason?: string },
+    ): Promise<{ toolPolicyVersion: number; unchanged: boolean }>;
   };
   activity: { list(query?: PageQuery): Promise<CursorPage<Activity>> };
   reviews: { list(query?: PageQuery): Promise<CursorPage<Review>> };
+  skills: {
+    archive(uid: string, expectedVersion: number): Promise<SkillMutationResult>;
+    create(body: {
+      changeReason?: string;
+      files: SkillFileInput[];
+      source?: 'api' | 'cli';
+    }): Promise<SkillMutationResult>;
+    delete(
+      uid: string,
+      body: { confirmationName: string; expectedVersion: number },
+    ): Promise<SkillMutationResult>;
+    export(uid: string): Promise<{ files: SkillFileInput[]; name: string }>;
+    exportVersion(uid: string, versionUid: string): Promise<{ files: SkillFileInput[] }>;
+    get(uid: string): Promise<SkillDetail>;
+    list(): Promise<{
+      items: Skill[];
+      usage: { archivedSkillCount: number; liveSkillCount: number; storedByteCount: number };
+    }>;
+    publish(
+      uid: string,
+      body: {
+        changeReason?: string;
+        deliveryMode: SkillDeliveryMode;
+        expectedVersion: number;
+        profileUids: string[];
+        riskConfirmed?: boolean;
+      },
+    ): Promise<SkillMutationResult>;
+    restoreVersion(
+      uid: string,
+      versionUid: string,
+      body: { changeReason?: string; expectedVersion: number },
+    ): Promise<SkillMutationResult>;
+    saveDraft(
+      uid: string,
+      body: {
+        changeReason?: string;
+        expectedVersion: number;
+        files: SkillFileInput[];
+        source?: 'api' | 'cli';
+      },
+    ): Promise<SkillMutationResult>;
+    setEnabled(
+      uid: string,
+      enabled: boolean,
+      expectedVersion: number,
+    ): Promise<SkillMutationResult>;
+    updateAudience(
+      uid: string,
+      body: {
+        deliveryMode: SkillDeliveryMode;
+        expectedVersion: number;
+        profileUids: string[];
+      },
+    ): Promise<SkillMutationResult>;
+    validate(files: SkillFileInput[]): Promise<SkillValidationResult>;
+  };
   webhooks: {
     create(body: {
-      url: string;
+      batchMaxEvents?: number;
+      deliveryMode?: 'batch' | 'single';
       description?: string | null;
       eventTypes: WebhookEvent[];
       forwardToolPayloads?: boolean;
+      url: string;
     }): Promise<{ uid: string; secret: string }>;
     delete(uid: string): Promise<void>;
+    getConfigurationVersion(
+      uid: string,
+      versionUid: string,
+    ): Promise<{ version: WebhookConfigurationVersion }>;
     list(): Promise<{ items: Webhook[] }>;
+    listConfigurationVersions(
+      uid: string,
+      query?: PageQuery,
+    ): Promise<CursorPage<ConfigurationVersionSummary>>;
+    restoreConfigurationVersion(
+      uid: string,
+      versionUid: string,
+      body: { expectedVersion: number; reason?: string },
+    ): Promise<{
+      configuration: WebhookConfiguration;
+      configurationVersion: number;
+      versionUid: string;
+    }>;
+    update(
+      uid: string,
+      body: Partial<WebhookConfiguration> & { expectedVersion: number; reason?: string },
+    ): Promise<{
+      configuration: WebhookConfiguration;
+      configurationVersion: number;
+      unchanged: boolean;
+      versionUid: string;
+    }>;
     verify: typeof verifyWebhookSignature;
   };
   request(

package/index.js

@@ -100,11 +100,19 @@ export class Rayrun {
       create: (body) => this.request('POST', '/connections', { body }),
       createOAuthLink: (uid) => this.request('POST', `/connections/${uid}/oauth-link`),
       delete: (uid) => this.request('DELETE', `/connections/${uid}`),
+      getConfigurationVersion: (uid, versionUid) =>
+        this.request('GET', `/connections/${uid}/history/${versionUid}`),
       index: (uid) => this.request('POST', `/connections/${uid}/index`),
       list: (query) => this.request('GET', '/connections', { query }),
+      listConfigurationVersions: (uid, query) =>
+        this.request('GET', `/connections/${uid}/history`, { query }),
+      restoreConfigurationVersion: (uid, versionUid, body) =>
+        this.request('POST', `/connections/${uid}/history/${versionUid}/restore`, { body }),
       setCredential: (uid, body) => this.request('PUT', `/connections/${uid}/credential`, { body }),
-      setEnabled: (uid, enabled) =>
-        this.request('PATCH', `/connections/${uid}`, { body: { enabled } }),
+      setEnabled: (uid, input) =>
+        this.request('PATCH', `/connections/${uid}`, {
+          body: typeof input === 'boolean' ? { enabled: input } : input,
+        }),
       setPolicy: (uid, mode) =>
         this.request('PATCH', `/connections/${uid}/policy`, { body: { mode } }),
     };
@@ -119,8 +127,20 @@ export class Rayrun {
       deploy: (connectionUid, toolUid, body) =>
         this.request('POST', `${toolHookPath(connectionUid, toolUid)}/deploy`, { body }),
       get: (connectionUid, toolUid) => this.request('GET', toolHookPath(connectionUid, toolUid)),
+      getDraftVersion: (connectionUid, toolUid, versionUid) =>
+        this.request('GET', `${toolHookPath(connectionUid, toolUid)}/history/${versionUid}`),
+      listDraftVersions: (connectionUid, toolUid, query) =>
+        this.request('GET', `${toolHookPath(connectionUid, toolUid)}/history`, { query }),
       listRuns: (connectionUid, toolUid, query) =>
         this.request('GET', `${toolHookPath(connectionUid, toolUid)}/runs`, { query }),
+      reset: (connectionUid, toolUid, body) =>
+        this.request('DELETE', toolHookPath(connectionUid, toolUid), { body }),
+      restoreDraft: (connectionUid, toolUid, versionUid, body) =>
+        this.request(
+          'POST',
+          `${toolHookPath(connectionUid, toolUid)}/history/${versionUid}/restore`,
+          { body },
+        ),
       saveDraft: (connectionUid, toolUid, body) =>
         this.request('PUT', toolHookPath(connectionUid, toolUid), { body }),
       setDeployment: (connectionUid, toolUid, body) =>
@@ -145,27 +165,69 @@ export class Rayrun {
       archive: archiveAccessProfile,
       create: (body) => this.request('POST', '/access-profiles', { body }),
       delete: archiveAccessProfile,
+      getConfigurationVersion: (uid, versionUid) =>
+        this.request('GET', `/access-profiles/${uid}/history/${versionUid}`),
       list: (query) => this.request('GET', '/access-profiles', { query }),
+      listConfigurationVersions: (uid, query) =>
+        this.request('GET', `/access-profiles/${uid}/history`, { query }),
       listTools: (uid, query) => this.request('GET', `/access-profiles/${uid}/tools`, { query }),
-      setPolicy: (uid, mode, expectedVersion) =>
+      restoreConfigurationVersion: (uid, versionUid, body) =>
+        this.request('POST', `/access-profiles/${uid}/history/${versionUid}/restore`, { body }),
+      setPolicy: (uid, mode, expectedVersion, reason) =>
         this.request('PATCH', `/access-profiles/${uid}/policy`, {
-          body: { expectedVersion, mode },
+          body: withoutUndefined({ expectedVersion, mode, reason }),
+          headers: { prefer: 'return=representation' },
         }),
       setToolPolicy: (uid, toolUid, body) =>
-        this.request('PATCH', `/access-profiles/${uid}/tools/${toolUid}/policy`, { body }),
-      update: (uid, body) => this.request('PATCH', `/access-profiles/${uid}`, { body }),
+        this.request('PATCH', `/access-profiles/${uid}/tools/${toolUid}/policy`, {
+          body,
+          headers: { prefer: 'return=representation' },
+        }),
+      update: (uid, body) =>
+        this.request('PATCH', `/access-profiles/${uid}`, {
+          body,
+          headers: { prefer: 'return=representation' },
+        }),
     };
     this.activity = { list: (query) => this.request('GET', '/activity', { query }) };
     this.reviews = { list: (query) => this.request('GET', '/reviews', { query }) };
+    this.skills = {
+      archive: (uid, expectedVersion) =>
+        this.request('POST', `/skills/${uid}/archive`, { body: { expectedVersion } }),
+      create: (body) => this.request('POST', '/skills', { body }),
+      delete: (uid, body) => this.request('DELETE', `/skills/${uid}`, { body }),
+      export: (uid) => this.request('GET', `/skills/${uid}/export`),
+      exportVersion: (uid, versionUid) =>
+        this.request('GET', `/skills/${uid}/versions/${versionUid}/export`),
+      get: (uid) => this.request('GET', `/skills/${uid}`),
+      list: () => this.request('GET', '/skills'),
+      publish: (uid, body) => this.request('POST', `/skills/${uid}/publish`, { body }),
+      restoreVersion: (uid, versionUid, body) =>
+        this.request('POST', `/skills/${uid}/versions/${versionUid}/restore`, { body }),
+      saveDraft: (uid, body) => this.request('PUT', `/skills/${uid}/draft`, { body }),
+      setEnabled: (uid, enabled, expectedVersion) =>
+        this.request('PATCH', `/skills/${uid}/enabled`, {
+          body: { enabled, expectedVersion },
+        }),
+      updateAudience: (uid, body) => this.request('PATCH', `/skills/${uid}/audience`, { body }),
+      validate: (files) => this.request('POST', '/skills/validate', { body: { files } }),
+    };
     this.webhooks = {
       create: (body) => this.request('POST', '/webhooks', { body }),
       delete: (uid) => this.request('DELETE', `/webhooks/${uid}`),
+      getConfigurationVersion: (uid, versionUid) =>
+        this.request('GET', `/webhooks/${uid}/history/${versionUid}`),
       list: () => this.request('GET', '/webhooks'),
+      listConfigurationVersions: (uid, query) =>
+        this.request('GET', `/webhooks/${uid}/history`, { query }),
+      restoreConfigurationVersion: (uid, versionUid, body) =>
+        this.request('POST', `/webhooks/${uid}/history/${versionUid}/restore`, { body }),
+      update: (uid, body) => this.request('PATCH', `/webhooks/${uid}`, { body }),
       verify: verifyWebhookSignature,
     };
   }
 
-  async request(method, path, { body, query, signal } = {}) {
+  async request(method, path, { body, headers, query, signal } = {}) {
     const url = new URL(`${this.baseUrl}/v1${path}`);
     for (const [name, value] of Object.entries(withoutUndefined(query ?? {}))) {
       url.searchParams.set(name, String(value));
@@ -179,6 +241,7 @@ export class Rayrun {
         response = await this.fetch(url, {
           body: body === undefined ? undefined : JSON.stringify(body),
           headers: withoutUndefined({
+            ...headers,
             authorization: `Bearer ${this.#apiKey}`,
             'content-type': body === undefined ? undefined : 'application/json',
             'user-agent': '@rayrun/sdk',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rayrun/sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Type-safe client for the Rayrun public API",
   "license": "MIT",
   "repository": {