@scalekit-sdk/node 2.2.0-beta.2 → 2.2.0-beta.3

package/reference.md

@@ -5187,6 +5187,313 @@ await scalekitClient.auth.updateLoginUserDetails(
 </dl>
 
 
+</dd>
+</dl>
+</details>
+
+## Actions
+
+<details><summary><code>client.actions.<a href="/src/actions.ts">executeTool</a>(params) -> Promise&lt;ExecuteToolResponse&gt;</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Executes a tool on behalf of a connected account using the high-level actions wrapper. This is a thin wrapper around `client.tools.executeTool` and is the primary entrypoint for agent-style tool execution in the Node SDK.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+// Execute a tool with a connected account ID
+const executeResponse = await scalekitClient.actions.executeTool({
+  toolName: 'gmail_send_email',
+  toolInput: {
+    to: 'user@example.com',
+    subject: 'Hello',
+    body: 'Hello from Scalekit Actions',
+  },
+  connectedAccountId: 'ca_123',
+});
+
+// Execute a tool by resolving the connected account via identifier + connector
+const executeResponse2 = await scalekitClient.actions.executeTool({
+  toolName: 'gmail_send_email',
+  toolInput: {
+    to: 'user@example.com',
+    subject: 'Test',
+    body: 'Body',
+  },
+  identifier: 'user@example.com',
+  connector: 'google_workspace',
+  organizationId: 'org_123',
+});
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**params:** `object`
+- `toolName: string` - Name of the tool to execute
+- `toolInput: Record<string, unknown>` - JSON payload passed as the tool's input parameters
+- `identifier?: string` - Connected account identifier (e.g., email, workspace ID)
+- `connectedAccountId?: string` - Direct ID of the connected account (`ca_...`)
+- `connector?: string` - Connector/provider name when using identifier-based lookup
+- `organizationId?: string` - Organization scope for identifier-based lookup
+- `userId?: string` - User scope for identifier-based lookup
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.actions.<a href="/src/actions.ts">getAuthorizationLink</a>(params) -> Promise&lt;GetMagicLinkForConnectedAccountResponse&gt;</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Generates a time-limited magic link to authorize or re-authorize a third-party account for a given connector and identifier, via the high-level actions wrapper.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+const magicLinkResponse = await scalekitClient.actions.getAuthorizationLink({
+  connectionName: 'notion',
+  identifier: 'workspace_123',
+  organizationId: 'org_123',
+});
+
+// Redirect the user to magicLinkResponse.link before it expires
+console.log(magicLinkResponse.link, magicLinkResponse.expiry);
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**params:** `object`
+- `connectionName?: string` - Connector identifier (e.g., `notion`, `google_workspace`)
+- `identifier?: string` - Connected account identifier (e.g., workspace ID, email)
+- `connectedAccountId?: string` - Optional connected account ID (`ca_...`)
+- `organizationId?: string` - Optional organization scope
+- `userId?: string` - Optional user scope
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.actions.<a href="/src/actions.ts">getOrCreateConnectedAccount</a>(params) -> Promise&lt;CreateConnectedAccountResponse&gt;</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Retrieves an existing connected account for a connector + identifier or creates one if it does not exist. This mirrors the Python `ActionClient.get_or_create_connected_account` behavior.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+import {
+  AuthorizationDetails,
+  OauthToken,
+} from '@scalekit-sdk/node';
+
+const oauthToken = new OauthToken({
+  accessToken: 'test_access_token',
+  refreshToken: 'test_refresh_token',
+  scopes: ['read', 'write'],
+});
+
+const authorizationDetails = new AuthorizationDetails({
+  details: {
+    case: 'oauthToken',
+    value: oauthToken,
+  },
+});
+
+const connectedAccountResponse = await scalekitClient.actions.getOrCreateConnectedAccount({
+  connectionName: 'gmail',
+  identifier: 'user@example.com',
+  authorizationDetails,
+  organizationId: 'org_123',
+});
+
+console.log(connectedAccountResponse.connectedAccount?.id);
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**params:** `object`
+- `connectionName: string` - Connector identifier (e.g., `gmail`, `notion`)
+- `identifier: string` - Connected account identifier (e.g., email, workspace ID)
+- `authorizationDetails?: AuthorizationDetails` - Optional auth details used when creating a new account
+- `organizationId?: string` - Optional organization scope
+- `userId?: string` - Optional user scope
+- `apiConfig?: Record<string, unknown>` - Optional API configuration used when creating a new account
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.actions.<a href="/src/actions.ts">request</a>(params) -> Promise&lt;AxiosResponse&lt;any&gt;&gt;</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Makes a proxied REST API call through Scalekit on behalf of a connected account. This mirrors the Python `ActionClient.request` helper and is useful for direct HTTP calls to third-party APIs.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+const response = await scalekitClient.actions.request({
+  connectionName: 'microsoft_graph',
+  identifier: 'user@example.com',
+  path: '/v1.0/me/messages',
+  method: 'GET',
+  queryParams: { '$top': 10 },
+});
+
+console.log(response.status, response.data);
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**params:** `object`
+- `connectionName: string` - Connector identifier to route the proxied call
+- `identifier: string` - Connected account identifier whose credentials are used
+- `path: string` - Target API path (e.g., `/v1.0/me/messages`)
+- `method?: string` - HTTP method (`GET`, `POST`, `PUT`, etc., default: `GET`)
+- `queryParams?: Record<string, unknown>` - URL query parameters
+- `body?: unknown` - JSON body payload
+- `formData?: Record<string, unknown>` - Form-encoded payload (alternative to `body`)
+- `headers?: Record<string, string>` - Additional HTTP headers to send
+- `timeoutMs?: number` - Optional request timeout in milliseconds
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
 </dd>
 </dl>
 </details>

package/src/actions.ts

@@ -0,0 +1,349 @@
+import { AxiosResponse } from "axios";
+import CoreClient from "./core";
+import ToolsClient from "./tools";
+import ConnectedAccountsClient from "./connected-accounts";
+import {
+  CreateConnectedAccount,
+  CreateConnectedAccountResponse,
+  DeleteConnectedAccountResponse,
+  GetConnectedAccountByIdentifierResponse,
+  GetMagicLinkForConnectedAccountResponse,
+  ListConnectedAccountsResponse,
+  UpdateConnectedAccount,
+  UpdateConnectedAccountResponse,
+} from "./pkg/grpc/scalekit/v1/connected_accounts/connected_accounts_pb";
+import { ExecuteToolResponse } from "./pkg/grpc/scalekit/v1/tools/tools_pb";
+
+/**
+ * This class is intended to be accessed via `ScalekitClient.actions`.
+ * It composes the existing ToolsClient and ConnectedAccountsClient
+ * without changing their behavior.
+ */
+export default class ActionsClient {
+  constructor(
+    private readonly tools: ToolsClient,
+    private readonly connectedAccounts: ConnectedAccountsClient,
+    private readonly coreClient: CoreClient
+  ) {}
+
+  /**
+   * Execute a tool on behalf of a connected account.
+   *
+   * Thin wrapper around ToolsClient.executeTool, reserved for future
+   * pre/post modifier support.
+   */
+  async executeTool(params: {
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    identifier?: string;
+    connectedAccountId?: string;
+    connector?: string;
+    organizationId?: string;
+    userId?: string;
+  }): Promise<ExecuteToolResponse> {
+    const {
+      toolName,
+      toolInput,
+      identifier,
+      connectedAccountId,
+      connector,
+      organizationId,
+      userId,
+    } = params;
+
+    if (!toolName?.trim()) {
+      throw new Error("toolName is required");
+    }
+
+    return this.tools.executeTool({
+      toolName,
+      identifier,
+      params: toolInput,
+      connectedAccountId,
+      connector,
+      organizationId,
+      userId,
+    });
+  }
+
+  /**
+   * Get an authorization magic link for a connected account.
+   */
+  async getAuthorizationLink(params: {
+    connectionName?: string;
+    identifier?: string;
+    connectedAccountId?: string;
+    organizationId?: string;
+    userId?: string;
+  }): Promise<GetMagicLinkForConnectedAccountResponse> {
+    const {
+      connectionName,
+      identifier,
+      connectedAccountId,
+      organizationId,
+      userId,
+    } = params;
+
+    return this.connectedAccounts.getMagicLinkForConnectedAccount({
+      connector: connectionName ?? "",
+      identifier: identifier ?? "",
+      organizationId,
+      userId,
+      connectedAccountId,
+    });
+  }
+
+  /**
+   * List connected accounts with optional filters.
+   */
+  async listConnectedAccounts(params?: {
+    connectionName?: string;
+    identifier?: string;
+    provider?: string;
+    organizationId?: string;
+    userId?: string;
+    pageSize?: number;
+    pageToken?: string;
+    query?: string;
+  }): Promise<ListConnectedAccountsResponse> {
+    return this.connectedAccounts.listConnectedAccounts({
+      organizationId: params?.organizationId,
+      userId: params?.userId,
+      connector: params?.connectionName,
+      identifier: params?.identifier,
+      provider: params?.provider,
+      pageSize: params?.pageSize,
+      pageToken: params?.pageToken,
+      query: params?.query,
+    });
+  }
+
+  /**
+   * Delete a connected account.
+   */
+  async deleteConnectedAccount(params: {
+    connectionName: string;
+    identifier: string;
+    connectedAccountId?: string;
+    organizationId?: string;
+    userId?: string;
+  }): Promise<DeleteConnectedAccountResponse> {
+    const {
+      connectionName,
+      identifier,
+      connectedAccountId,
+      organizationId,
+      userId,
+    } = params;
+
+    return this.connectedAccounts.deleteConnectedAccount({
+      connector: connectionName,
+      identifier,
+      organizationId,
+      userId,
+      connectedAccountId,
+    });
+  }
+
+  /**
+   * Get connected account authorization details.
+   */
+  async getConnectedAccount(params: {
+    connectionName: string;
+    identifier: string;
+    connectedAccountId?: string;
+    organizationId?: string;
+    userId?: string;
+  }): Promise<GetConnectedAccountByIdentifierResponse> {
+    const {
+      connectionName,
+      identifier,
+      connectedAccountId,
+      organizationId,
+      userId,
+    } = params;
+
+    return this.connectedAccounts.getConnectedAccountByIdentifier({
+      connector: connectionName,
+      identifier,
+      organizationId,
+      userId,
+      connectedAccountId,
+    });
+  }
+
+  /**
+   * Create a new connected account.
+   *
+   * This helper accepts a high-level payload and builds the
+   * underlying CreateConnectedAccount message.
+   */
+  async createConnectedAccount(params: {
+    connectionName: string;
+    identifier: string;
+    authorizationDetails: CreateConnectedAccount["authorizationDetails"];
+    organizationId?: string;
+    userId?: string;
+    apiConfig?: Record<string, unknown>;
+  }): Promise<CreateConnectedAccountResponse> {
+    const {
+      connectionName,
+      identifier,
+      authorizationDetails,
+      organizationId,
+      userId,
+      apiConfig,
+    } = params;
+
+    if (!connectionName?.trim()) {
+      throw new Error("connectionName is required");
+    }
+    if (!identifier?.trim()) {
+      throw new Error("identifier is required");
+    }
+
+    const connectedAccount = new CreateConnectedAccount({
+      authorizationDetails,
+      ...(apiConfig != null && {
+        apiConfig: apiConfig as unknown as CreateConnectedAccount["apiConfig"],
+      }),
+    });
+
+    return this.connectedAccounts.createConnectedAccount({
+      connector: connectionName,
+      identifier,
+      connectedAccount,
+      organizationId,
+      userId,
+    });
+  }
+
+  /**
+   * Get an existing connected account or create a new one if it doesn't exist.
+   */
+  async getOrCreateConnectedAccount(params: {
+    connectionName: string;
+    identifier: string;
+    authorizationDetails?: CreateConnectedAccount["authorizationDetails"];
+    organizationId?: string;
+    userId?: string;
+    apiConfig?: Record<string, unknown>;
+  }): Promise<CreateConnectedAccountResponse> {
+    const {
+      connectionName,
+      identifier,
+      authorizationDetails,
+      organizationId,
+      userId,
+      apiConfig,
+    } = params;
+
+    return this.connectedAccounts.getOrCreateConnectedAccount({
+      connector: connectionName,
+      identifier,
+      authorizationDetails,
+      organizationId,
+      userId,
+      apiConfig,
+    });
+  }
+
+  /**
+   * Update an existing connected account.
+   */
+  async updateConnectedAccount(params: {
+    connectionName: string;
+    identifier: string;
+    authorizationDetails?: UpdateConnectedAccount["authorizationDetails"];
+    organizationId?: string;
+    userId?: string;
+    connectedAccountId?: string;
+    apiConfig?: UpdateConnectedAccount["apiConfig"];
+  }): Promise<UpdateConnectedAccountResponse> {
+    const {
+      connectionName,
+      identifier,
+      authorizationDetails,
+      organizationId,
+      userId,
+      connectedAccountId,
+      apiConfig,
+    } = params;
+
+    const connectedAccount = new UpdateConnectedAccount({
+      ...(authorizationDetails && { authorizationDetails }),
+      ...(apiConfig != null && { apiConfig }),
+    });
+
+    return this.connectedAccounts.updateConnectedAccount({
+      connector: connectionName,
+      identifier,
+      connectedAccount,
+      organizationId,
+      userId,
+      connectedAccountId,
+    });
+  }
+
+  /**
+   * Make a proxied REST API call on behalf of a connected account.
+   */
+  async request(params: {
+    connectionName: string;
+    identifier: string;
+    path: string;
+    method?: string;
+    queryParams?: Record<string, unknown>;
+    body?: unknown;
+    formData?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+  }): Promise<AxiosResponse<any>> {
+    const {
+      connectionName,
+      identifier,
+      path,
+      method = "GET",
+      queryParams,
+      body,
+      formData,
+      headers,
+      timeoutMs,
+    } = params;
+
+    if (!connectionName?.trim()) {
+      throw new Error("connectionName is required");
+    }
+    if (!identifier?.trim()) {
+      throw new Error("identifier is required");
+    }
+    if (!path?.trim()) {
+      throw new Error("path is required");
+    }
+
+    const url = `${this.coreClient.envUrl.replace(/\/$/, "")}/proxy${path}`;
+    const timeout = timeoutMs ?? 30_000;
+
+    const proxyHeaders: Record<string, string> = {
+      connection_name: connectionName,
+      Connection_name: connectionName,
+      identifier,
+      ...(headers ?? {}),
+    };
+
+    
+    
+    return this.coreClient.connectExec(
+      (config) => this.coreClient.axios.request(config),
+      {
+        url,
+        method: method.toUpperCase(),
+        params: queryParams,
+        data: body ?? formData,
+        headers: proxyHeaders,
+        timeout,
+      }
+    );
+  }
+}
+

package/src/core.ts

@@ -23,7 +23,7 @@ export default class CoreClient {
   public keys: JWK[] = [];
   public accessToken: string | null = null;
   public axios: Axios;
-  public sdkVersion = `Scalekit-Node/2.2.0-beta.2`;
+  public sdkVersion = `Scalekit-Node/2.2.0-beta.3`;
   public apiVersion = "20260310";
   public userAgent = `${this.sdkVersion} Node/${process.version} (${
     process.platform

package/src/scalekit.ts

@@ -17,6 +17,7 @@ import SessionClient from './session';
 import RoleClient from './role';
 import PermissionClient from './permission';
 import WebAuthnClient from './webauthn';
+import ActionsClient from './actions';
 import { IdpInitiatedLoginClaims, IdTokenClaim, User } from './types/auth';
 import { AuthenticationOptions, AuthenticationResponse, AuthorizationUrlOptions, GrantType, LogoutUrlOptions, RefreshTokenResponse ,TokenValidationOptions } from './types/scalekit';
 import { WebhookVerificationError, ScalekitValidateTokenFailureException } from './errors/base-exception';
@@ -64,6 +65,7 @@ export default class ScalekitClient {
   readonly domain: DomainClient;
   readonly tools: ToolsClient;
   readonly connectedAccounts: ConnectedAccountsClient;
+  readonly actions: ActionsClient;
   readonly directory: DirectoryClient;
   readonly passwordless: PasswordlessClient;
   readonly user: UserClient;
@@ -97,6 +99,11 @@ export default class ScalekitClient {
       this.grpcConnect,
       this.coreClient
     );
+    this.actions = new ActionsClient(
+      this.tools,
+      this.connectedAccounts,
+      this.coreClient
+    );
     this.directory = new DirectoryClient(this.grpcConnect, this.coreClient);
     this.passwordless = new PasswordlessClient(
       this.grpcConnect,