@rayrun/sdk 0.2.1 → 0.4.0

package/README.md

@@ -9,13 +9,46 @@ import { Rayrun } from '@rayrun/sdk';
 
 const rayrun = new Rayrun({ apiKey: process.env.RAYRUN_API_KEY });
 const { items: connections } = await rayrun.connections.list();
+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, activity, review queues, and webhooks. Safe reads retry rate limits, server errors,
-and transient network failures; writes do not retry automatically.
+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.
+
+Inspect the effective policy applied to one connected client without reproducing policy logic in
+your application:
+
+```js
+const { items: effectivePolicy } = await rayrun.clients.listTools(clientUid, {
+  query: 'create issue',
+});
+```
+
+Each result includes the effective decision and the workspace, access-profile, or client layer that
+restricted it.
+
+## Reuse one access ceiling across clients
+
+```js
+const { profile } = await rayrun.accessProfiles.create({
+  name: 'Support agents',
+  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,
+  name: 'Support agents',
+});
+await rayrun.clients.setAccessProfile(clientUid, profile.uid, clientToolPolicyVersion);
+```
+
+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.
 
 ## Stream code run-ahead
 
@@ -72,10 +105,13 @@ const valid = verifyWebhookSignature({
 ```
 
 After verification, parse the body as `WebhookPayload`. Every event has a stable `id`, `type`, and
-`occurredAt`; its `data` shape is narrowed by `type`. Use `id` to deduplicate retries.
+`occurredAt`; its `data` shape is narrowed by `type`. Delivery is at least once, so make processing
+idempotent and deduplicate on `id`.
 For `activity.call`, `arguments` and `result` contain the captured tool payloads, or `null` when
 capture was disabled for that connection, the webhook did not opt in with
-`forwardToolPayloads: true`, or no result existed.
+`forwardToolPayloads: true`, or no result existed. `payloadCaptured` distinguishes a metadata-only
+webhook from a call where capture was disabled. Rayrun observes MCP tool arguments and results; it
+does not receive the host's full Claude or GPT prompt, assistant response, or surrounding chat.
 
 ```ts
 import type { WebhookPayload } from '@rayrun/sdk';

package/index.d.ts

@@ -10,6 +10,7 @@ export type JsonValue =
 export type PageQuery = { cursor?: string; limit?: number };
 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 Connection = {
   authorizedAt: string | null;
@@ -24,6 +25,7 @@ export type Connection = {
   slug: string;
   status: 'connected' | 'disabled' | 'error' | 'indexing' | 'needs-authorization' | 'new';
   toolAccessMode: ToolAccessMode;
+  toolPolicyVersion: number;
 };
 export type CatalogEntry = {
   authType: Connection['authType'];
@@ -50,15 +52,54 @@ export type Tool = {
   title: string | null;
 };
 export type Client = {
+  accessProfile: Pick<AccessProfile, 'name' | 'uid'> | null;
   clientName: string;
   grantedAt: string;
   lastUsedAt: string | null;
   redirectHost: string;
   revokedAt: string | null;
   toolAccessMode: ToolAccessMode;
+  toolPolicyVersion: number;
   uid: string;
   userName: string;
 };
+export type ClientTool = {
+  approved: boolean;
+  clientDecision: ToolDecision | null;
+  effectiveDecision: ToolDecision;
+  effectiveReason:
+    | 'definition-unapproved'
+    | 'workspace-tool-rule'
+    | 'workspace-default'
+    | 'client-profile-tool-rule'
+    | 'client-profile-default'
+    | 'client-tool-rule'
+    | 'client-default'
+    | 'multiple-layers'
+    | 'workspace-and-client';
+  name: string;
+  riskLevel: Risk;
+  riskReason: string;
+  serviceName: string;
+  uid: string;
+  workspaceDecision: ToolDecision | null;
+};
+export type AccessProfile = {
+  assignedClientCount: number;
+  description: string;
+  name: string;
+  toolAccessMode: AccessProfileMode;
+  toolPolicyVersion: number;
+  uid: string;
+};
+export type AccessProfileTool = {
+  available: boolean;
+  decision: ToolDecision | null;
+  name: string;
+  riskLevel: Risk;
+  serviceName: string;
+  uid: string;
+};
 export type Activity = {
   calledAt: string;
   clientName: string | null;
@@ -111,7 +152,17 @@ export type WebhookEvent =
   | 'review.changed'
   | 'tool.definition-changed'
   | 'tool.policy-changed';
-export type WebhookEnvelope<T extends Exclude<WebhookEvent, '*'>, D> = {
+export type WebhookDeliveryEvent = Exclude<WebhookEvent, '*'> | 'webhook.test';
+export type ToolPolicyEventType =
+  | 'access-profile-archived'
+  | 'access-profile-assigned'
+  | 'access-profile-changed'
+  | 'access-profile-created'
+  | 'client-mode-changed'
+  | 'client-tool-rule-changed'
+  | 'workspace-mode-changed'
+  | 'workspace-tool-rule-changed';
+export type WebhookEnvelope<T extends WebhookDeliveryEvent, D> = {
   data: D;
   id: string;
   occurredAt: string;
@@ -124,12 +175,23 @@ export type WebhookPayload =
         activityId: string;
         arguments: JsonValue;
         calledAt: string;
+        clientUid: string | null;
         connectionUid: string | null;
         errorCode: string | null;
+        payloadCaptured: boolean;
         policyDecision: ToolDecision | null;
         result: JsonValue;
+        sessionUid: string;
         succeeded: boolean | null;
         toolName: string;
+        userUid: string | null;
+      }
+    >
+  | WebhookEnvelope<
+      'webhook.test',
+      {
+        endpointUid: string;
+        message: string;
       }
     >
   | WebhookEnvelope<
@@ -169,7 +231,10 @@ export type WebhookPayload =
       {
         connectionUid: string | null;
         decision: ToolDecision | null;
-        eventType: string;
+        eventType: ToolPolicyEventType;
+        metadata: Record<string, JsonValue>;
+        oauthClientConsentUid: string | null;
+        oauthClientName: string | null;
         toolUid: string | null;
       }
     >;
@@ -208,7 +273,7 @@ export class Rayrun {
         | { kind: 'openapi'; specificationUrl: string; baseUrl?: string; name?: string },
     ): Promise<{ connection: { uid: string } }>;
     createOAuthLink(uid: string): Promise<{ authorizationUrl: string }>;
-    delete(uid: string): Promise<void>;
+    delete(uid: string, expectedVersion: number): Promise<void>;
     index(uid: string): Promise<{ enqueued: boolean }>;
     list(query?: PageQuery): Promise<CursorPage<Connection>>;
     setCredential(uid: string, body: Credential): Promise<{ enqueued: boolean }>;
@@ -219,7 +284,7 @@ export class Rayrun {
     setPolicy(uid: string, mode: ToolAccessMode): Promise<void>;
   };
   tools: {
-    list(query?: PageQuery & { connectionUid?: string }): Promise<CursorPage<Tool>>;
+    list(query?: PageQuery & { connectionUid?: string; query?: string }): Promise<CursorPage<Tool>>;
     setPolicy(
       connectionUid: string,
       toolUid: string,
@@ -228,6 +293,12 @@ export class Rayrun {
   };
   clients: {
     list(query?: PageQuery): Promise<CursorPage<Client>>;
+    listTools(uid: string, query?: PageQuery & { query?: string }): Promise<CursorPage<ClientTool>>;
+    setAccessProfile(
+      uid: string,
+      profileUid: string | null,
+      expectedVersion: number,
+    ): Promise<void>;
     setPolicy(uid: string, mode: Exclude<ToolAccessMode, 'custom'>): Promise<void>;
     setToolPolicy(
       uid: string,
@@ -235,6 +306,28 @@ export class Rayrun {
       body: { decision: ToolDecision | null; riskConfirmed?: boolean },
     ): Promise<void>;
   };
+  accessProfiles: {
+    archive(uid: string, expectedVersion: number): Promise<void>;
+    create(body: { description: string; name: string }): Promise<{ profile: AccessProfile }>;
+    /** @deprecated Use archive. */
+    delete(uid: string, expectedVersion: number): Promise<void>;
+    list(query?: PageQuery): Promise<CursorPage<AccessProfile>>;
+    listTools(uid: string, query?: PageQuery): Promise<CursorPage<AccessProfileTool>>;
+    setPolicy(uid: string, mode: AccessProfileMode, expectedVersion: number): Promise<void>;
+    setToolPolicy(
+      uid: string,
+      toolUid: string,
+      body: {
+        decision: ToolDecision | null;
+        expectedVersion: number;
+        riskConfirmed?: boolean;
+      },
+    ): Promise<void>;
+    update(
+      uid: string,
+      body: { description: string; expectedVersion: number; name: string },
+    ): Promise<void>;
+  };
   activity: { list(query?: PageQuery): Promise<CursorPage<Activity>> };
   reviews: { list(query?: PageQuery): Promise<CursorPage<Review>> };
   webhooks: {

package/index.js

@@ -114,10 +114,31 @@ export class Rayrun {
     };
     this.clients = {
       list: (query) => this.request('GET', '/clients', { query }),
+      listTools: (uid, query) => this.request('GET', `/clients/${uid}/tools`, { query }),
+      setAccessProfile: (uid, profileUid, expectedVersion) =>
+        this.request('PATCH', `/clients/${uid}/access-profile`, {
+          body: { expectedVersion, profileUid },
+        }),
       setPolicy: (uid, mode) => this.request('PATCH', `/clients/${uid}/policy`, { body: { mode } }),
       setToolPolicy: (uid, toolUid, body) =>
         this.request('PATCH', `/clients/${uid}/tools/${toolUid}/policy`, { body }),
     };
+    const archiveAccessProfile = (uid, expectedVersion) =>
+      this.request('DELETE', `/access-profiles/${uid}`, { query: { expectedVersion } });
+    this.accessProfiles = {
+      archive: archiveAccessProfile,
+      create: (body) => this.request('POST', '/access-profiles', { body }),
+      delete: archiveAccessProfile,
+      list: (query) => this.request('GET', '/access-profiles', { query }),
+      listTools: (uid, query) => this.request('GET', `/access-profiles/${uid}/tools`, { query }),
+      setPolicy: (uid, mode, expectedVersion) =>
+        this.request('PATCH', `/access-profiles/${uid}/policy`, {
+          body: { expectedVersion, mode },
+        }),
+      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.activity = { list: (query) => this.request('GET', '/activity', { query }) };
     this.reviews = { list: (query) => this.request('GET', '/reviews', { query }) };
     this.webhooks = {

package/package.json

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