@tsg-dsp/tsg-sdk 0.0.0-stage → 0.20.1

package/dist/sso/sso-management.sdk.js

@@ -0,0 +1,152 @@
+import { ClientDto, UserDto } from "../vendor/sso-bridge-dtos/index.js";
+import { validateResponse, validateResponseArray } from "../utils/validate.js";
+/**
+ * Manage SSO Bridge users, OAuth clients, and permissions.
+ *
+ * Accessible via {@link SsoSdk.management}.
+ * @example
+ * ```ts
+ * const users = await sdk.sso.management.getUsers({ page: 1, perPage: 10 });
+ * const newClient = await sdk.sso.management.createClient({
+ *   name: "my-app",
+ *   redirectUris: ["http://localhost:3000/callback"],
+ * });
+ * ```
+ */
+export class SsoManagementSdk {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    // ── Users ──────────────────────────────────────────────────────────────
+    /**
+     * List SSO users with optional pagination.
+     * @param options - Pagination and sorting options.
+     * @returns An array of validated {@link UserDto} instances.
+     */
+    async getUsers(options) {
+        const { data } = await this.client.GET("/users", {
+            params: {
+                query: {
+                    page: options?.page,
+                    per_page: options?.perPage,
+                    order: options?.order,
+                    order_by: options?.orderBy
+                }
+            }
+        });
+        return validateResponseArray(UserDto, data ?? []);
+    }
+    /**
+     * Create a new SSO user.
+     * @param user - The user details.
+     * @returns The created {@link UserDto}.
+     */
+    async createUser(user) {
+        const { data } = await this.client.POST("/users/create", {
+            body: user
+        });
+        return validateResponse(UserDto, data);
+    }
+    /**
+     * Update an existing SSO user.
+     * @param id - The user ID.
+     * @param user - The fields to update.
+     * @returns The updated {@link UserDto}.
+     */
+    async updateUser(id, user) {
+        const { data } = await this.client.PATCH("/users/update/{id}", {
+            params: { path: { id } },
+            body: user
+        });
+        return validateResponse(UserDto, data);
+    }
+    /**
+     * Delete an SSO user.
+     * @param id - The user ID.
+     * @returns The deletion response.
+     */
+    async deleteUser(id) {
+        const { data } = await this.client.DELETE("/users/{id}", {
+            params: { path: { id } }
+        });
+        return data;
+    }
+    /**
+     * Reset two-factor authentication for an SSO user.
+     *
+     * The user will need to re-enroll in 2FA on their next login.
+     * @param id - The user ID.
+     * @returns The reset response.
+     */
+    async resetUser2FA(id) {
+        const { data } = await this.client.POST("/users/{id}/reset-2fa", {
+            params: { path: { id } }
+        });
+        return data;
+    }
+    // ── Clients ────────────────────────────────────────────────────────────
+    /**
+     * List OAuth clients with optional pagination.
+     * @param options - Pagination and sorting options.
+     * @returns An array of validated {@link ClientDto} instances.
+     */
+    async getClients(options) {
+        const { data } = await this.client.GET("/clients", {
+            params: {
+                query: {
+                    page: options?.page,
+                    per_page: options?.perPage,
+                    order: options?.order,
+                    order_by: options?.orderBy
+                }
+            }
+        });
+        return validateResponseArray(ClientDto, data ?? []);
+    }
+    /**
+     * Register a new OAuth client.
+     * @param client - The client details including name and redirect URIs.
+     * @returns The created {@link ClientDto}.
+     */
+    async createClient(client) {
+        const { data } = await this.client.POST("/clients/create", {
+            body: client
+        });
+        return validateResponse(ClientDto, data);
+    }
+    /**
+     * Update an existing OAuth client.
+     * @param id - The client ID.
+     * @param client - The fields to update.
+     * @returns The updated {@link ClientDto}.
+     */
+    async updateClient(id, client) {
+        const { data } = await this.client.PATCH("/clients/update/{id}", {
+            params: { path: { id } },
+            body: client
+        });
+        return validateResponse(ClientDto, data);
+    }
+    /**
+     * Delete an OAuth client.
+     * @param id - The client ID.
+     * @returns The deletion response.
+     */
+    async deleteClient(id) {
+        const { data } = await this.client.DELETE("/clients/{id}", {
+            params: { path: { id } }
+        });
+        return data;
+    }
+    // ── Permissions ────────────────────────────────────────────────────────
+    /**
+     * Get all available permissions in the SSO system.
+     * @returns The permissions configuration.
+     */
+    async getPermissions() {
+        const { data } = await this.client.GET("/permissions");
+        return data;
+    }
+}
+//# sourceMappingURL=sso-management.sdk.js.map

package/dist/sso/sso-management.sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso-management.sdk.js","sourceRoot":"","sources":["../../src/sso/sso-management.sdk.ts"],"names":[],"mappings":"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"}

package/dist/sso/sso.sdk.d.ts

@@ -0,0 +1,75 @@
+import type { OpenIDConfiguration, TokenResponse } from "../auth/auth.types.js";
+import type { SsoBridgeClient } from "../client.js";
+import type { TsgSdkAuthConfig } from "../config/sdk.config.js";
+import { SsoManagementSdk } from "./sso-management.sdk.js";
+/**
+ * OpenID Connect integration, token management, and user/client administration
+ * via the TSG SSO Bridge.
+ *
+ * Requires `ssoBridgeBaseUrl` to be set in the SDK configuration.
+ *
+ * This module provides:
+ * - Access token acquisition and refresh using OIDC flows.
+ * - Authorization code exchange (with optional PKCE).
+ * - OpenID discovery and JWKS retrieval.
+ * - User and OAuth client management via the {@link SsoManagementSdk | management} sub-module.
+ * @example
+ * ```ts
+ * const token = await sdk.sso.getAccessToken();
+ * const users = await sdk.sso.management.getUsers();
+ * ```
+ */
+export declare class SsoSdk {
+    private readonly ssoBridgeBaseUrl;
+    private readonly authProvider;
+    /** User and OAuth client management operations. */
+    readonly management: SsoManagementSdk;
+    constructor(ssoBridgeBaseUrl: string, authConfig?: TsgSdkAuthConfig, ssoBridgeClient?: SsoBridgeClient);
+    /**
+     * Get an access token from the SSO bridge using the configured authentication method.
+     * @returns The access token string.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.AUTH_FAILED} if no auth configuration is provided or token acquisition fails.
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Fetch the OpenID Connect discovery document from the SSO bridge.
+     *
+     * The `.well-known/openid-configuration` endpoint is always resolved at
+     * the server origin, regardless of any path prefix in `ssoBridgeBaseUrl`.
+     * @returns The parsed {@link OpenIDConfiguration}.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.REQUEST_FAILED} if the discovery request fails.
+     */
+    getOpenIdConfiguration(): Promise<OpenIDConfiguration>;
+    /**
+     * Fetch the JSON Web Key Set (JWKS) from the SSO bridge.
+     *
+     * The JWKS URI is discovered automatically via the OpenID configuration.
+     * These keys can be used to verify tokens issued by the SSO bridge.
+     * @returns An object containing an array of {@link JsonWebKey} entries.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.REQUEST_FAILED} if the JWKS fetch fails.
+     */
+    getJwks(): Promise<{
+        keys: JsonWebKey[];
+    }>;
+    /**
+     * Exchange an OAuth 2.0 authorization code for access and refresh tokens.
+     *
+     * Supports PKCE by accepting an optional `codeVerifier`.
+     * @param code - The authorization code received from the authorization endpoint.
+     * @param redirectUri - The redirect URI that was used in the original authorization request.
+     * @param clientId - The OAuth client ID.
+     * @param codeVerifier - Optional PKCE code verifier for public clients.
+     * @returns A {@link TokenResponse} containing the access token and optional refresh token.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.AUTH_FAILED} if the exchange fails.
+     */
+    exchangeAuthorizationCode(code: string, redirectUri: string, clientId: string, codeVerifier?: string): Promise<TokenResponse>;
+    /**
+     * Refresh an access token using an OAuth 2.0 refresh token.
+     * @param refreshToken - The refresh token.
+     * @param clientId - The OAuth client ID.
+     * @returns A {@link TokenResponse} containing the new access token.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.AUTH_FAILED} if the refresh fails.
+     */
+    refreshAccessToken(refreshToken: string, clientId: string): Promise<TokenResponse>;
+}
+//# sourceMappingURL=sso.sdk.d.ts.map

package/dist/sso/sso.sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso.sdk.d.ts","sourceRoot":"","sources":["../../src/sso/sso.sdk.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,MAAM;IAMf,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IALnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,mDAAmD;IACnD,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;gBAGnB,gBAAgB,EAAE,MAAM,EACzC,UAAU,CAAC,EAAE,gBAAgB,EAC7B,eAAe,CAAC,EAAE,eAAe;IAoBnC;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAWvC;;;;;;;OAOG;IACG,sBAAsB,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAe5D;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC;IAahD;;;;;;;;;;OAUG;IACG,yBAAyB,CAC7B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,aAAa,CAAC;IA6BzB;;;;;;OAMG;IACG,kBAAkB,CACtB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC;CAwB1B"}

package/dist/sso/sso.sdk.js

@@ -0,0 +1,147 @@
+import { AuthProvider } from "../auth/auth.provider.js";
+import { SdkError, SdkErrorCode } from "../utils/errors.js";
+import { SsoManagementSdk } from "./sso-management.sdk.js";
+/**
+ * OpenID Connect integration, token management, and user/client administration
+ * via the TSG SSO Bridge.
+ *
+ * Requires `ssoBridgeBaseUrl` to be set in the SDK configuration.
+ *
+ * This module provides:
+ * - Access token acquisition and refresh using OIDC flows.
+ * - Authorization code exchange (with optional PKCE).
+ * - OpenID discovery and JWKS retrieval.
+ * - User and OAuth client management via the {@link SsoManagementSdk | management} sub-module.
+ * @example
+ * ```ts
+ * const token = await sdk.sso.getAccessToken();
+ * const users = await sdk.sso.management.getUsers();
+ * ```
+ */
+export class SsoSdk {
+    ssoBridgeBaseUrl;
+    authProvider;
+    /** User and OAuth client management operations. */
+    management;
+    constructor(ssoBridgeBaseUrl, authConfig, ssoBridgeClient) {
+        this.ssoBridgeBaseUrl = ssoBridgeBaseUrl;
+        this.authProvider = new AuthProvider(authConfig, ssoBridgeBaseUrl);
+        if (ssoBridgeClient) {
+            this.management = new SsoManagementSdk(ssoBridgeClient);
+        }
+        else {
+            this.management = new Proxy({}, {
+                get(_target, prop) {
+                    if (typeof prop === "symbol")
+                        return undefined;
+                    return () => {
+                        throw new SdkError("SSO management client not available. This should not happen when ssoBridgeBaseUrl is configured.", SdkErrorCode.NOT_CONFIGURED);
+                    };
+                }
+            });
+        }
+    }
+    /**
+     * Get an access token from the SSO bridge using the configured authentication method.
+     * @returns The access token string.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.AUTH_FAILED} if no auth configuration is provided or token acquisition fails.
+     */
+    async getAccessToken() {
+        const token = await this.authProvider.getAccessToken();
+        if (!token) {
+            throw new SdkError("No auth configuration provided", SdkErrorCode.AUTH_FAILED);
+        }
+        return token;
+    }
+    /**
+     * Fetch the OpenID Connect discovery document from the SSO bridge.
+     *
+     * The `.well-known/openid-configuration` endpoint is always resolved at
+     * the server origin, regardless of any path prefix in `ssoBridgeBaseUrl`.
+     * @returns The parsed {@link OpenIDConfiguration}.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.REQUEST_FAILED} if the discovery request fails.
+     */
+    async getOpenIdConfiguration() {
+        // .well-known is always at the server root, not under any API prefix
+        const origin = new URL(this.ssoBridgeBaseUrl).origin;
+        const url = `${origin}/.well-known/openid-configuration`;
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new SdkError(`Failed to fetch OpenID configuration (${response.status})`, SdkErrorCode.REQUEST_FAILED, response.status);
+        }
+        return response.json();
+    }
+    /**
+     * Fetch the JSON Web Key Set (JWKS) from the SSO bridge.
+     *
+     * The JWKS URI is discovered automatically via the OpenID configuration.
+     * These keys can be used to verify tokens issued by the SSO bridge.
+     * @returns An object containing an array of {@link JsonWebKey} entries.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.REQUEST_FAILED} if the JWKS fetch fails.
+     */
+    async getJwks() {
+        const config = await this.getOpenIdConfiguration();
+        const response = await fetch(config.jwks_uri);
+        if (!response.ok) {
+            throw new SdkError(`Failed to fetch JWKS (${response.status})`, SdkErrorCode.REQUEST_FAILED, response.status);
+        }
+        return response.json();
+    }
+    /**
+     * Exchange an OAuth 2.0 authorization code for access and refresh tokens.
+     *
+     * Supports PKCE by accepting an optional `codeVerifier`.
+     * @param code - The authorization code received from the authorization endpoint.
+     * @param redirectUri - The redirect URI that was used in the original authorization request.
+     * @param clientId - The OAuth client ID.
+     * @param codeVerifier - Optional PKCE code verifier for public clients.
+     * @returns A {@link TokenResponse} containing the access token and optional refresh token.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.AUTH_FAILED} if the exchange fails.
+     */
+    async exchangeAuthorizationCode(code, redirectUri, clientId, codeVerifier) {
+        const config = await this.getOpenIdConfiguration();
+        const params = new URLSearchParams();
+        params.set("grant_type", "authorization_code");
+        params.set("code", code);
+        params.set("redirect_uri", redirectUri);
+        params.set("client_id", clientId);
+        if (codeVerifier) {
+            params.set("code_verifier", codeVerifier);
+        }
+        const response = await fetch(config.token_endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: params.toString()
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            throw new SdkError(`Authorization code exchange failed (${response.status}): ${body}`, SdkErrorCode.AUTH_FAILED, response.status);
+        }
+        return response.json();
+    }
+    /**
+     * Refresh an access token using an OAuth 2.0 refresh token.
+     * @param refreshToken - The refresh token.
+     * @param clientId - The OAuth client ID.
+     * @returns A {@link TokenResponse} containing the new access token.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.AUTH_FAILED} if the refresh fails.
+     */
+    async refreshAccessToken(refreshToken, clientId) {
+        const config = await this.getOpenIdConfiguration();
+        const params = new URLSearchParams();
+        params.set("grant_type", "refresh_token");
+        params.set("refresh_token", refreshToken);
+        params.set("client_id", clientId);
+        const response = await fetch(config.token_endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: params.toString()
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            throw new SdkError(`Token refresh failed (${response.status}): ${body}`, SdkErrorCode.AUTH_FAILED, response.status);
+        }
+        return response.json();
+    }
+}
+//# sourceMappingURL=sso.sdk.js.map

package/dist/sso/sso.sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso.sdk.js","sourceRoot":"","sources":["../../src/sso/sso.sdk.ts"],"names":[],"mappings":"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"}

package/dist/transfers/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./transfers.sdk.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/transfers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transfers/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/dist/transfers/index.js

@@ -0,0 +1,2 @@
+export * from "./transfers.sdk.js";
+//# sourceMappingURL=index.js.map

package/dist/transfers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/transfers/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/dist/transfers/transfers.sdk.d.ts

@@ -0,0 +1,155 @@
+import { DataPlaneAddressDto, TransferDetailDto, TransferProcess, TransferProcessDto } from "@tsg-dsp/common-dsp";
+import type { ControlPlaneClient } from "../client.js";
+import type { PollingOptions } from "../utils/polling.js";
+/**
+ * Request, monitor, and control Dataspace Protocol data transfer processes.
+ *
+ * A transfer process follows the DSP state machine:
+ * `REQUESTED → STARTED → COMPLETED` (or `SUSPENDED` / `TERMINATED`).
+ *
+ * This module provides methods to:
+ * - Initiate transfers under an existing contract agreement.
+ * - Start, complete, suspend, or terminate transfers.
+ * - Poll for state transitions (e.g. wait until a transfer has started).
+ * @example
+ * ```ts
+ * const transfer = await sdk.transfers.transferAndWaitForStart(
+ *   agreementId,
+ *   participantId,
+ *   remoteAddress,
+ *   "application/json",
+ * );
+ * console.log(transfer.state); // "STARTED"
+ * ```
+ */
+export declare class TransferSdk {
+    private readonly client;
+    constructor(client: ControlPlaneClient);
+    /**
+     * List all transfer processes known to the control plane.
+     * @returns An array of validated {@link TransferDetailDto} instances.
+     */
+    listTransfers(): Promise<TransferDetailDto[]>;
+    /**
+     * Initiate a new data transfer under an existing contract agreement.
+     * @param agreementId - The agreement ID that authorizes this transfer.
+     * @param participantId - The remote participant's ID (DID), used as audience.
+     * @param remoteAddress - The remote participant's DSP protocol endpoint.
+     * @param format - The desired transfer format (e.g. `"application/json"`).
+     * @param returnDto - When `true`, returns the raw {@link TransferProcessDto}.
+     * @returns The created {@link TransferProcess} (or raw DTO).
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.REQUEST_FAILED} if the request is rejected.
+     */
+    requestTransfer(agreementId: string, participantId: string, remoteAddress: string, format: string, returnDto: true): Promise<TransferProcessDto>;
+    requestTransfer(agreementId: string, participantId: string, remoteAddress: string, format: string, returnDto?: false): Promise<TransferProcess>;
+    /**
+     * List the dataflows tracked for a transfer process.
+     *
+     * Each dataflow represents the data plane's execution of the transfer, with
+     * its own signaling state (`PREPARED`, `STARTED`, …) and pull address.
+     * @param processId - The transfer process ID.
+     * @returns The dataflows tracked for the transfer.
+     */
+    getTransferDataflows(processId: string): Promise<{
+        id: string;
+        transferProcessId: string;
+        dataPlaneId: string;
+        datasetId?: string | undefined;
+        state: "INITIALIZED" | "PREPARING" | "PREPARED" | "STARTING" | "STARTED" | "SUSPENDED" | "COMPLETED" | "TERMINATED";
+        dataAddress?: {
+            endpoint: string;
+            properties: {
+                name: string;
+                value: string;
+            }[];
+        } | undefined;
+    }[]>;
+    /**
+     * Get the details of a transfer process by its process ID.
+     * @param processId - The unique transfer process ID.
+     * @returns A validated {@link TransferDetailDto}.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.NOT_FOUND} if the transfer does not exist.
+     */
+    getTransfer(processId: string): Promise<TransferDetailDto>;
+    /**
+     * Start a transfer process (provider-side).
+     *
+     * Transitions the transfer from `REQUESTED` to `STARTED`.
+     * @param processId - The transfer process ID.
+     * @param dataAddress - Optional data plane address to use for the transfer.
+     * @returns The start response.
+     */
+    startTransfer(processId: string, dataAddress?: DataPlaneAddressDto): Promise<{
+        status?: string | undefined;
+    }>;
+    /**
+     * Mark a transfer process as completed.
+     * @param processId - The transfer process ID.
+     * @returns The completion response.
+     */
+    completeTransfer(processId: string): Promise<{
+        status?: string | undefined;
+    }>;
+    /**
+     * Terminate a transfer process.
+     * @param processId - The transfer process ID.
+     * @param code - Optional machine-readable termination reason code.
+     * @param reason - Optional human-readable termination reason.
+     * @returns The termination response.
+     */
+    terminateTransfer(processId: string, code?: string, reason?: string): Promise<{}>;
+    /**
+     * Suspend a transfer process.
+     *
+     * A suspended transfer can later be resumed or terminated.
+     * @param processId - The transfer process ID.
+     * @param reason - Optional human-readable suspension reason.
+     * @returns The suspension response.
+     */
+    suspendTransfer(processId: string, reason?: string): Promise<{
+        status?: string | undefined;
+    }>;
+    /**
+     * Poll until a transfer reaches the given target state.
+     * @param processId - The transfer process ID.
+     * @param targetState - The desired state (e.g. `"STARTED"`, `"COMPLETED"`).
+     * @param options - Polling interval and retry configuration.
+     * @returns The {@link TransferDetailDto} once the target state is reached.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.POLLING_TIMEOUT} if the state is not reached within the configured retries.
+     */
+    waitForState(processId: string, targetState: TransferDetailDto["state"], options?: PollingOptions): Promise<TransferDetailDto>;
+    /**
+     * Poll until a transfer reaches the `STARTED` state.
+     *
+     * Shorthand for `waitForState(processId, "STARTED", options)`.
+     * @param processId - The transfer process ID.
+     * @param options - Polling interval and retry configuration.
+     * @returns The {@link TransferDetailDto} with `state === "STARTED"`.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.POLLING_TIMEOUT} if the state is not reached in time.
+     */
+    waitForStart(processId: string, options?: PollingOptions): Promise<TransferDetailDto>;
+    /**
+     * Poll until a transfer reaches the `COMPLETED` state.
+     *
+     * Shorthand for `waitForState(processId, "COMPLETED", options)`.
+     * @param processId - The transfer process ID.
+     * @param options - Polling interval and retry configuration.
+     * @returns The {@link TransferDetailDto} with `state === "COMPLETED"`.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.POLLING_TIMEOUT} if the state is not reached in time.
+     */
+    waitForCompletion(processId: string, options?: PollingOptions): Promise<TransferDetailDto>;
+    /**
+     * Initiate a transfer and wait for it to start in one call.
+     *
+     * Combines {@link requestTransfer} and {@link waitForStart}.
+     * @param agreementId - The agreement ID that authorizes this transfer.
+     * @param participantId - The remote participant's ID (DID).
+     * @param remoteAddress - The remote participant's DSP protocol endpoint.
+     * @param format - The desired transfer format.
+     * @param pollingOptions - Optional polling configuration.
+     * @returns The {@link TransferDetailDto} once the transfer has started.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.POLLING_TIMEOUT} if the transfer does not start in time.
+     */
+    transferAndWaitForStart(agreementId: string, participantId: string, remoteAddress: string, format: string, pollingOptions?: PollingOptions): Promise<TransferDetailDto>;
+}
+//# sourceMappingURL=transfers.sdk.d.ts.map

package/dist/transfers/transfers.sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfers.sdk.d.ts","sourceRoot":"","sources":["../../src/transfers/transfers.sdk.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EACnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQ1D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,kBAAkB;IAEvD;;;OAGG;IACG,aAAa;IAKnB;;;;;;;;;OASG;IACG,eAAe,CACnB,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,IAAI,GACd,OAAO,CAAC,kBAAkB,CAAC;IACxB,eAAe,CACnB,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,KAAK,GAChB,OAAO,CAAC,eAAe,CAAC;IAuB3B;;;;;;;OAOG;IACG,oBAAoB,CAAC,SAAS,EAAE,MAAM;;;;;;;;;;;;;;IAU5C;;;;;OAKG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM;IAUnC;;;;;;;OAOG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,mBAAmB;;;IAWxE;;;;OAIG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM;;;IAUxC;;;;;;OAMG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAWzE;;;;;;;OAOG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;;;IAWxD;;;;;;;OAOG;IACG,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,iBAAiB,CAAC,OAAO,CAAC,EACvC,OAAO,CAAC,EAAE,cAAc;IAS1B;;;;;;;;OAQG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;IAQ9D;;;;;;;;OAQG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;IAQnE;;;;;;;;;;;OAWG;IACG,uBAAuB,CAC3B,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,EACd,cAAc,CAAC,EAAE,cAAc;CAUlC"}