@rayrun/sdk 0.2.0 → 0.3.0

package/README.md

@@ -14,8 +14,28 @@ const { items: connections } = await rayrun.connections.list();
 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.
+
+## 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
 
@@ -73,6 +93,11 @@ 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.
+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. `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

@@ -1,8 +1,16 @@
 /* oxlint-disable perfectionist/sort-classes, perfectionist/sort-modules, perfectionist/sort-object-types, perfectionist/sort-union-types -- Public types follow the documented API resource order. */
 export type CursorPage<T> = { items: T[]; page: { nextCursor: string | null } };
+export type JsonValue =
+  | boolean
+  | null
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: 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;
@@ -17,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'];
@@ -43,15 +52,33 @@ 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 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;
@@ -77,6 +104,7 @@ export type Webhook = {
   description: string | null;
   enabled: boolean;
   eventTypes: WebhookEvent[];
+  forwardToolPayloads: boolean;
   uid: string;
   url: string;
 };
@@ -103,7 +131,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;
@@ -114,12 +152,25 @@ export type WebhookPayload =
       'activity.call',
       {
         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<
@@ -159,7 +210,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;
       }
     >;
@@ -198,7 +252,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 }>;
@@ -218,6 +272,11 @@ export class Rayrun {
   };
   clients: {
     list(query?: PageQuery): Promise<CursorPage<Client>>;
+    setAccessProfile(
+      uid: string,
+      profileUid: string | null,
+      expectedVersion: number,
+    ): Promise<void>;
     setPolicy(uid: string, mode: Exclude<ToolAccessMode, 'custom'>): Promise<void>;
     setToolPolicy(
       uid: string,
@@ -225,6 +284,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: {
@@ -232,6 +313,7 @@ export class Rayrun {
       url: string;
       description?: string | null;
       eventTypes: WebhookEvent[];
+      forwardToolPayloads?: boolean;
     }): Promise<{ uid: string; secret: string }>;
     delete(uid: string): Promise<void>;
     list(): Promise<{ items: Webhook[] }>;

package/index.js

@@ -80,6 +80,8 @@ export const verifyWebhookSignature = ({
 };
 
 export class Rayrun {
+  #apiKey;
+
   constructor({
     apiKey,
     baseUrl = 'https://ray.run',
@@ -88,7 +90,7 @@ export class Rayrun {
     if (!apiKey) throw new TypeError('Rayrun requires an apiKey.');
     if (!fetchImplementation) throw new TypeError('Rayrun requires a fetch implementation.');
 
-    this.apiKey = apiKey;
+    this.#apiKey = apiKey;
     this.baseUrl = baseUrl.replace(/\/$/u, '');
     this.fetch = fetchImplementation;
 
@@ -112,10 +114,30 @@ export class Rayrun {
     };
     this.clients = {
       list: (query) => this.request('GET', '/clients', { 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 = {
@@ -140,7 +162,7 @@ export class Rayrun {
         response = await this.fetch(url, {
           body: body === undefined ? undefined : JSON.stringify(body),
           headers: withoutUndefined({
-            authorization: `Bearer ${this.apiKey}`,
+            authorization: `Bearer ${this.#apiKey}`,
             'content-type': body === undefined ? undefined : 'application/json',
             'user-agent': '@rayrun/sdk',
           }),
@@ -266,6 +288,8 @@ export class RayrunCodeRunAheadSession {
 }
 
 export class RayrunGateway {
+  #accessToken;
+
   constructor({
     accessToken,
     baseUrl = 'https://ray.run',
@@ -274,7 +298,7 @@ export class RayrunGateway {
     if (!accessToken) throw new TypeError('RayrunGateway requires an accessToken.');
     if (!fetchImplementation) throw new TypeError('RayrunGateway requires a fetch implementation.');
 
-    this.accessToken = accessToken;
+    this.#accessToken = accessToken;
     this.baseUrl = baseUrl.replace(/\/$/u, '');
     this.fetch = fetchImplementation;
     this.codeRunAhead = {
@@ -298,7 +322,7 @@ export class RayrunGateway {
     const response = await this.fetch(`${this.baseUrl}/mcp/run-ahead`, {
       body: JSON.stringify(body),
       headers: {
-        authorization: `Bearer ${this.accessToken}`,
+        authorization: `Bearer ${this.#accessToken}`,
         'content-type': 'application/json',
         'user-agent': '@rayrun/sdk',
       },

package/package.json

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