@nurama/sdk 1.4.0 → 1.4.1

package/src/routes/joinLink.ts

@@ -5,6 +5,16 @@ import {
   type CreateJoinLinkPayload,
   type UpdateJoinLinkPayload,
   type RedeemJoinLinkResult,
+  type ListJoinRequestsResponse,
+  type ListMyJoinRequestsResponse,
+  type ApproveJoinRequestResponse,
+  type RejectJoinRequestRequest,
+  type RejectJoinRequestResponse,
+  type UpdateJoinRequestCooldownRequest,
+  type ProjectJoinRequest,
+  type ListBansResponse,
+  type CreateResourceBanRequest,
+  type ResourceBan,
 } from '@nurama/types';
 
 // --- Query Parameter Interfaces ---
@@ -49,6 +59,129 @@ export default function createJoinLinkMethods(client: NuramaClient) {
       });
     },
 
+    /** The queue of people waiting on a decision for this project. */
+    async getJoinRequests(params: { projectId: string }): Promise<ListJoinRequestsResponse> {
+      if (!params?.projectId) throw new Error('projectId is required.');
+      return client._request<ListJoinRequestsResponse>({
+        method: 'GET',
+        endpoint: '/v1/join-links/requests',
+        params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * The caller's own requests still waiting on a decision.
+     *
+     * Needs no `projectId`: it is scoped server-side to the caller, who is not
+     * a member of the projects they are waiting on and so cannot read those
+     * projects' queues.
+     */
+    async getMyJoinRequests(): Promise<ListMyJoinRequestsResponse> {
+      return client._request<ListMyJoinRequestsResponse>({
+        method: 'GET',
+        endpoint: '/v1/join-links/requests/mine',
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Approve a request and admit the person.
+     *
+     * Seats and the link's remaining uses are re-checked here, not when the
+     * request was made — a queue outlives the capacity that existed when it was
+     * filled, so approval can legitimately fail on a seat limit.
+     */
+    async approveJoinRequest(requestId: string, projectId: string): Promise<ApproveJoinRequestResponse> {
+      if (!requestId) throw new Error('requestId is required.');
+      if (!projectId) throw new Error('projectId is required.');
+      return client._request<ApproveJoinRequestResponse>({
+        method: 'POST',
+        endpoint: `/v1/join-links/requests/${requestId}/approve`,
+        body: { projectId },
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Reject a request, optionally barring the person.
+     *
+     * Passing `ban` is destructive beyond the refusal: a ban REMOVES an existing
+     * membership, so it can take away access the person already had in scope.
+     * It is a separate field for that reason, never implied by the rejection.
+     */
+    async rejectJoinRequest(requestId: string, data: RejectJoinRequestRequest): Promise<RejectJoinRequestResponse> {
+      if (!requestId) throw new Error('requestId is required.');
+      if (!data?.projectId) throw new Error('projectId is required.');
+      return client._request<RejectJoinRequestResponse>({
+        method: 'POST',
+        endpoint: `/v1/join-links/requests/${requestId}/reject`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Change or lift the cooldown on a rejected request.
+     *
+     * Only a rejected request has one; `reapplyAfter: null` lifts it, letting
+     * the person ask again straight away. A barred person is refused — the ban
+     * already blocks every path, so lifting that is the action that matters.
+     */
+    async updateJoinRequestCooldown(
+      requestId: string,
+      data: UpdateJoinRequestCooldownRequest,
+    ): Promise<ProjectJoinRequest> {
+      if (!requestId) throw new Error('requestId is required.');
+      if (!data?.projectId) throw new Error('projectId is required.');
+      return client._request<ProjectJoinRequest>({
+        method: 'PATCH',
+        endpoint: `/v1/join-links/requests/${requestId}/cooldown`,
+        body: { projectId: data.projectId, reapplyAfter: data.reapplyAfter ?? null },
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Bar someone, without a request to refuse.
+     *
+     * Destructive: the ban REMOVES every membership the person holds in its
+     * scope, so a `workspace` ban clears them out of every project in it. An
+     * owner cannot be barred, and neither can you bar yourself.
+     */
+    async createResourceBan(data: CreateResourceBanRequest): Promise<ResourceBan> {
+      if (!data?.projectId) throw new Error('projectId is required.');
+      if (!data?.userId) throw new Error('userId is required.');
+      if (!data?.scope) throw new Error('scope is required.');
+      return client._request<ResourceBan>({
+        method: 'POST',
+        endpoint: '/v1/join-links/bans',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /** People barred from this project, newest first. */
+    async getResourceBans(params: { projectId: string }): Promise<ListBansResponse> {
+      if (!params?.projectId) throw new Error('projectId is required.');
+      return client._request<ListBansResponse>({
+        method: 'GET',
+        endpoint: '/v1/join-links/bans',
+        params,
+        sendJWT: true,
+      });
+    },
+
+    /** Lift a ban. It does not restore any membership the ban removed. */
+    async liftResourceBan(banId: string): Promise<ResourceBan> {
+      if (!banId) throw new Error('banId is required.');
+      return client._request<ResourceBan>({
+        method: 'DELETE',
+        endpoint: `/v1/join-links/bans/${banId}`,
+        sendJWT: true,
+      });
+    },
+
     /** Update a join link's settings (role, mode, domains, expiry, enable/disable). */
     async updateJoinLink(linkId: string, data: UpdateJoinLinkPayload): Promise<JoinLinkResponse> {
       if (!linkId) throw new Error('linkId is required.');

package/src/routes/oauthGrant.ts

@@ -0,0 +1,64 @@
+import NuramaClient from '../NuramaClient.js';
+
+/**
+ * One application a user has authorised over OAuth.
+ *
+ * A grant is the record of consent: the scopes approved, and the tie binding
+ * every token issued under it. Revoking one withdraws the application's
+ * access.
+ */
+export interface OAuthGrantSummary {
+  /** Opaque identifier; pass to `revokeGrant`. */
+  grantId: string;
+  clientId: string | null;
+  /**
+   * The application's name.
+   *
+   * Chosen by the application itself when `verified` is false — treat it as
+   * display text from an untrusted source, never as identification.
+   */
+  clientName: string | null;
+  /**
+   * Whether Nurama configured this application.
+   *
+   * False for one that registered itself through Dynamic Client Registration:
+   * it picked its own name and nobody reviewed it.
+   */
+  verified: boolean;
+  /** Scopes the user approved, from the backend's token-scope registry. */
+  scopes: string[];
+  grantedAt: string;
+  expiresAt: string | null;
+}
+
+export default function createOAuthGrantMethods(client: NuramaClient) {
+  return {
+    /**
+     * List the applications the caller has authorised, newest first.
+     * Expired grants are omitted by the server.
+     */
+    async listGrants(): Promise<OAuthGrantSummary[]> {
+      const res = await client._request<{ results: OAuthGrantSummary[] }>({
+        method: 'GET',
+        endpoint: '/v1/oauth-grants',
+        sendJWT: true,
+        bypassCache: true,
+      });
+      return res.results;
+    },
+
+    /**
+     * Withdraw an application's access: the grant and every token issued
+     * under it. An access token already in flight stays valid until it
+     * expires, so revocation is not instantaneous for a request under way.
+     */
+    async revokeGrant(grantId: string): Promise<void> {
+      if (!grantId) throw new Error('grantId is required.');
+      return client._request<void>({
+        method: 'DELETE',
+        endpoint: `/v1/oauth-grants/${grantId}`,
+        sendJWT: true,
+      });
+    },
+  };
+}

package/src/routes/socket.ts

@@ -110,6 +110,33 @@ const LIFECYCLE_LISTENER_EVENTS = new Set([
   'reconnect',
 ]);
 
+/** First reconnect delay; socket.io doubles it per failed attempt, up to RECONNECTION_DELAY_MAX, ±50% jitter. */
+const RECONNECTION_DELAY = 1000;
+const RECONNECTION_DELAY_MAX = 30000;
+
+/**
+ * Extra first-retry delay, up to this, after the SERVER closed the connection ("transport close"): a ws deploy
+ * or restart drops every client of that server at once, and without it they would all reconnect within the
+ * same second. Network drops ("ping timeout", "transport error") keep the normal 1s retry.
+ */
+const SERVER_CLOSE_RECONNECT_SPREAD = 10000;
+
+/**
+ * Spread reconnects after a server-side close (see SERVER_CLOSE_RECONNECT_SPREAD). Sets the manager's next
+ * delay from the socket's 'disconnect', which socket.io emits before it schedules the retry, and restores the
+ * normal delay on 'connect'. Channels share one manager, so the last channel's draw wins, which is fine.
+ */
+const spreadReconnectAfterServerClose = (socket: any): void => {
+  const manager = socket.io;
+  if (typeof manager?.reconnectionDelay !== 'function') return;
+  socket.on('disconnect', (reason: string) => {
+    if (reason === 'transport close') {
+      manager.reconnectionDelay(RECONNECTION_DELAY + Math.random() * SERVER_CLOSE_RECONNECT_SPREAD);
+    }
+  });
+  socket.on('connect', () => manager.reconnectionDelay(RECONNECTION_DELAY));
+};
+
 export default function createSocketMethods(client: NuramaClient) {
   // Track active socket connections
   const activeConnections: Record<string, SocketChannel> = {};
@@ -215,9 +242,12 @@ export default function createSocketMethods(client: NuramaClient) {
 
       // Reconnection configuration for resilience
       reconnection: socketOptions.autoReconnect,
-      reconnectionAttempts: 10,           // Maximum reconnection attempts before giving up
-      reconnectionDelay: 1000,             // Start with 1 second delay
-      reconnectionDelayMax: 30000,         // Max delay of 30 seconds between attempts
+      // Never give up: the server may refuse connections for a while (busy, or a deploy draining), and after a
+      // final failure socket.io stops for good without telling the app (the manager's 'reconnect_failed' never
+      // reaches socket listeners). Retries settle at one every ~30s.
+      reconnectionAttempts: Infinity,
+      reconnectionDelay: RECONNECTION_DELAY,
+      reconnectionDelayMax: RECONNECTION_DELAY_MAX,
       randomizationFactor: 0.5,            // Add jitter to avoid thundering herd problem
 
       // Connection timeout
@@ -244,14 +274,27 @@ export default function createSocketMethods(client: NuramaClient) {
     // handlers across reconnections, so they will fire once connected.
     activeConnections[channel] = socketChannel;
 
+    spreadReconnectAfterServerClose(socket);
+
     // Setup event listeners
     return new Promise((resolve, reject) => {
       let settled = false;
+      let hasConnected = false;
 
       // Handle connection (initial or after reconnection)
       socket.on('connect', () => {
         _log(`Connected to channel: ${channel}`);
         activeConnections[channel] = socketChannel;
+        if (hasConnected) {
+          // A second 'connect' on the same socket is socket.io reconnecting it (the manager emits 'reconnect',
+          // but socket listeners never see that). Notify app-level onReconnect listeners so they can
+          // REST-refetch any gap of server->client messages missed while the transport was down (socket.io has
+          // no replay across a reconnect).
+          _log(`Reconnected to channel ${channel}`);
+          const reconnectListeners = socketChannel.listeners['reconnect'] || new Set();
+          reconnectListeners.forEach(listener => listener({ type: 'reconnect' }));
+        }
+        hasConnected = true;
         if (!settled) {
           settled = true;
           resolve(socketChannel);
@@ -270,23 +313,6 @@ export default function createSocketMethods(client: NuramaClient) {
         }
       });
 
-      // Handle reconnection attempts
-      socket.on('reconnect_attempt', (attempt: number) => {
-        _log(`Reconnection attempt ${attempt} for channel: ${channel}`);
-      });
-
-      // Handle successful reconnection
-      socket.on('reconnect', (attempt: number) => {
-        _log(`Reconnected to channel ${channel} after ${attempt} attempts`);
-        // Ensure activeConnections is up to date after reconnect
-        activeConnections[channel] = socketChannel;
-        // Notify app-level onReconnect listeners so they can REST-refetch any
-        // gap of server->client messages missed while the transport was down
-        // (socket.io has no replay across a reconnect).
-        const reconnectListeners = socketChannel.listeners['reconnect'] || new Set();
-        reconnectListeners.forEach(listener => listener({ type: 'reconnect', attempt }));
-      });
-
       // Handle reconnection failure — only reject when socket.io gives up entirely
       socket.on('reconnect_failed', () => {
         _log(`Reconnection failed for channel ${channel} after maximum attempts`);
@@ -423,9 +449,9 @@ export default function createSocketMethods(client: NuramaClient) {
 
       // Reconnection configuration for resilience
       reconnection: socketOptions.autoReconnect,
-      reconnectionAttempts: 10,
-      reconnectionDelay: 1000,
-      reconnectionDelayMax: 30000,
+      reconnectionAttempts: Infinity,      // as connect(): never give up silently
+      reconnectionDelay: RECONNECTION_DELAY,
+      reconnectionDelayMax: RECONNECTION_DELAY_MAX,
       randomizationFactor: 0.5,
 
       // Connection timeout
@@ -446,6 +472,8 @@ export default function createSocketMethods(client: NuramaClient) {
       listeners: {},
     };
 
+    spreadReconnectAfterServerClose(socket);
+
     // Setup event listeners
     return new Promise((resolve, reject) => {
       // Handle connection
@@ -461,16 +489,6 @@ export default function createSocketMethods(client: NuramaClient) {
         reject(error);
       });
 
-      // Handle reconnection attempts
-      socket.on('reconnect_attempt', (attempt: number) => {
-        _log(`Reconnection attempt ${attempt} for public channel: ${channel}`);
-      });
-
-      // Handle successful reconnection
-      socket.on('reconnect', (attempt: number) => {
-        _log(`Reconnected to public channel ${channel} after ${attempt} attempts`);
-      });
-
       // Handle reconnection failure
       socket.on('reconnect_failed', () => {
         _log(`Reconnection failed for public channel ${channel} after maximum attempts`);

package/src/routes/token.ts

@@ -22,7 +22,14 @@ export type TokenScope =
   | 'assets:read'
   | 'assets:write'
   | 'projects:read'
-  | 'workspaces:read';
+  | 'projects:write'
+  | 'workspaces:read'
+  | 'workspaces:write'
+  | 'convos:read'
+  | 'convos:write'
+  | 'notifications:read'
+  | 'notifications:write'
+  | 'ai:use';
 
 /**
  * The shape returned by `listTokens` and (without the `token` field)
@@ -50,6 +57,16 @@ export interface CreateTokenData {
   expiresAt?: string | null;
 }
 
+export interface UpdateTokenScopesData {
+  /**
+   * The COMPLETE new scope set, not a delta — the same shape
+   * `createToken` takes, so what a token may do is always stated in
+   * full rather than accumulated through edits nobody can review.
+   * At least one scope.
+   */
+  scopes: TokenScope[];
+}
+
 export interface CreateTokenResponse extends TokenSummary {
   /**
    * The raw secret. Returned ONLY in this response. The server keeps a
@@ -97,6 +114,28 @@ export default function createTokenMethods(client: NuramaClient) {
       });
     },
 
+    /**
+     * Replace the scopes on one of the caller's Personal Access Tokens.
+     *
+     * `scopes` is the complete new set, not a delta. This exists because
+     * the scope registry grows over time: a token minted before a scope
+     * existed cannot hold it, and without this the only remedy is minting
+     * a replacement and reconfiguring everywhere the old one is used.
+     *
+     * The change takes effect on the token's very next request. Scopes
+     * remain a ceiling, never a floor — widening a token never lets it do
+     * anything its owner cannot already do.
+     */
+    async updateTokenScopes(tokenId: string, data: UpdateTokenScopesData): Promise<TokenSummary> {
+      if (!tokenId) throw new Error('tokenId is required.');
+      return client._request<TokenSummary>({
+        method: 'PATCH',
+        endpoint: `/v1/tokens/${tokenId}`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
     /**
      * Revoke one of the caller's Personal Access Tokens. The revocation
      * is immediate — the token will return 401 on the very next request.

package/src/version.ts

@@ -14,9 +14,9 @@ export interface SDKVersionInfo {
 }
 
 export const SDK_VERSION: SDKVersionInfo = {
-  version: '1.4.0',
-  buildTimestamp: '2026-10-03T16:23:07.694Z',
-  buildHash: '60ddbec0797c9d1bdf96aaf49b69dda5',
-  gitCommit: 'c000da4',
+  version: '1.4.1',
+  buildTimestamp: '2026-10-10T06:58:40.258Z',
+  buildHash: 'f6505e2eb9725dc8d239bb401ced8f88',
+  gitCommit: '1c00e18',
   dirty: false,
 };