@rayrun/sdk 0.4.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,160 @@ 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
+
+Hooks are versioned TypeScript adapters hosted and sandboxed by Rayrun. Pull the generated types and
+draft, test it without a live upstream call, then create an immutable shadow or active revision.
+
+```js
+const { hook } = await rayrun.hooks.get(connectionUid, toolUid);
+
+const tested = await rayrun.hooks.test(connectionUid, toolUid, {
+  source: hook.draftSource,
+  config: hook.draftConfig,
+  arguments: { query: 'release' },
+  mockResult: { items: [] },
+});
+
+const saved = await rayrun.hooks.saveDraft(connectionUid, toolUid, {
+  source: hook.draftSource,
+  config: hook.draftConfig,
+  expectedVersion: hook.version,
+  reason: 'Normalize upstream release results',
+});
+
+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
+it with `revisionUid: null`. Every mutation uses `expectedVersion`; fetch and reconcile instead of
+blindly retrying a `version_conflict`. Use a full-control API key for hook writes. Read-only keys can
+inspect source, generated declarations, revision history, and deployed-run metadata; captured logs
+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
 
@@ -83,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;
@@ -51,6 +79,116 @@ export type Tool = {
   inputSchema: Record<string, unknown>;
   title: string | null;
 };
+export type ToolHookPublicContract = {
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+};
+export type ToolHookRevision = {
+  config: Record<string, JsonValue>;
+  createdAt: string;
+  publicContract: ToolHookPublicContract | null;
+  revisionNumber: number;
+  source: string;
+  sourceHash: string;
+  uid: string;
+  upstreamDefinitionHash: string;
+};
+export type ToolHook = {
+  activeRevisionStale: boolean;
+  activeRevisionUid: string | null;
+  currentDraftRevisionNumber: number;
+  draftConfig: Record<string, JsonValue>;
+  draftSource: string;
+  hookUid: string | null;
+  revisions: ToolHookRevision[];
+  shadowRevisionStale: boolean;
+  shadowRevisionUid: string | null;
+  target: {
+    available: boolean;
+    definitionHash: string | null;
+    inputSchema: Record<string, unknown>;
+    name: string;
+    outputSchema: Record<string, unknown> | null;
+    toolUid: string;
+  };
+  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';
+  message: string;
+};
+export type ToolHookTestFailure = {
+  durationMs: number;
+  error: {
+    code: 'invalid_arguments' | 'invalid_outcome' | 'invalid_output' | 'runtime_error' | 'timeout';
+    message: string;
+  };
+  logs: ToolHookLogEntry[];
+  status: 'failed';
+};
+export type ToolHookBeforeTestResult =
+  | {
+      durationMs: number;
+      logs: ToolHookLogEntry[];
+      outcome:
+        | { action: 'continue'; arguments: JsonValue }
+        | { action: 'reject'; message: string; reason: string }
+        | { action: 'require_approval'; arguments: JsonValue; reason: string };
+      status: 'completed';
+    }
+  | ToolHookTestFailure;
+export type ToolHookAfterTestResult =
+  | {
+      durationMs: number;
+      logs: ToolHookLogEntry[];
+      outcome:
+        | { action: 'return'; result: JsonValue }
+        | { action: 'fail'; message: string; reason: string };
+      status: 'completed';
+    }
+  | ToolHookTestFailure;
+export type ToolHookRun = {
+  createdAt: string;
+  differsFromActive: boolean | null;
+  durationMs: number;
+  errorMessage: string | null;
+  id: string;
+  logs: ToolHookLogEntry[] | null;
+  outcome: 'approval-required' | 'continued' | 'failed' | 'rejected' | 'returned';
+  requestId: string;
+  revisionUid: string;
+  shadow: boolean;
+  stage: 'after' | 'before';
+  uid: string;
+};
 export type Client = {
   accessProfile: Pick<AccessProfile, 'name' | 'uid'> | null;
   clientName: string;
@@ -86,6 +224,7 @@ export type ClientTool = {
 };
 export type AccessProfile = {
   assignedClientCount: number;
+  assignedSkillCount: number;
   description: string;
   name: string;
   toolAccessMode: AccessProfileMode;
@@ -100,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;
@@ -120,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';
@@ -150,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';
@@ -222,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 }
@@ -243,6 +517,7 @@ export const CODE_RUN_AHEAD_META_KEY: 'io.rayrun/run-ahead-session';
 
 export class RayrunApiError extends Error {
   code: string;
+  diagnostics: Array<{ column?: number; line?: number; message: string }>;
   requestId: string | null;
   status: number;
 }
@@ -273,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: {
@@ -291,6 +591,81 @@ export class Rayrun {
       body: { decision: ToolDecision | null; riskConfirmed?: boolean; riskOverride?: Risk | null },
     ): Promise<void>;
   };
+  hooks: {
+    deploy(
+      connectionUid: string,
+      toolUid: string,
+      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<{
+      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,
+      body: {
+        expectedVersion: number;
+        mode: 'active' | 'shadow';
+        revisionUid: string | null;
+      },
+    ): Promise<{ hook: ToolHook }>;
+    test(
+      connectionUid: string,
+      toolUid: string,
+      body: {
+        arguments: JsonValue;
+        config?: Record<string, JsonValue>;
+        mockResult?: JsonValue;
+        source: string;
+      },
+    ): Promise<{
+      after?: ToolHookAfterTestResult;
+      before: ToolHookBeforeTestResult;
+      publicContract: ToolHookPublicContract | null;
+      sourceHash: string;
+    }>;
+  };
   clients: {
     list(query?: PageQuery): Promise<CursorPage<Client>>;
     listTools(uid: string, query?: PageQuery & { query?: string }): Promise<CursorPage<ClientTool>>;
@@ -308,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

@@ -1,10 +1,11 @@
 import { createHmac, timingSafeEqual } from 'node:crypto';
 
 export class RayrunApiError extends Error {
-  constructor(message, { code, requestId, status }) {
+  constructor(message, { code, diagnostics = [], requestId, status }) {
     super(message);
     this.name = 'RayrunApiError';
     this.code = code;
+    this.diagnostics = diagnostics;
     this.requestId = requestId;
     this.status = status;
   }
@@ -99,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 } }),
     };
@@ -112,6 +121,33 @@ export class Rayrun {
       setPolicy: (connectionUid, toolUid, body) =>
         this.request('PATCH', `/connections/${connectionUid}/tools/${toolUid}/policy`, { body }),
     };
+    const toolHookPath = (connectionUid, toolUid) =>
+      `/connections/${connectionUid}/tools/${toolUid}/hook`;
+    this.hooks = {
+      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) =>
+        this.request('POST', `${toolHookPath(connectionUid, toolUid)}/deployment`, { body }),
+      test: (connectionUid, toolUid, body) =>
+        this.request('POST', `${toolHookPath(connectionUid, toolUid)}/test`, { body }),
+    };
     this.clients = {
       list: (query) => this.request('GET', '/clients', { query }),
       listTools: (uid, query) => this.request('GET', `/clients/${uid}/tools`, { query }),
@@ -129,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));
@@ -163,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',
@@ -189,6 +268,7 @@ export class Rayrun {
           problem?.error?.message ?? `Rayrun API request failed with HTTP ${response.status}.`,
           {
             code: problem?.error?.code ?? 'request_failed',
+            diagnostics: Array.isArray(problem?.diagnostics) ? problem.diagnostics : [],
             requestId: problem?.error?.requestId ?? response.headers.get('rayrun-request-id'),
             status: response.status,
           },

package/package.json

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