@datalayer/core 0.0.12 → 0.0.13

package/lib/api/iam/oauth2.js

@@ -0,0 +1,309 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * OAuth2 API functions for the Datalayer platform.
+ *
+ * Provides functions for OAuth2 authorization flows with various providers.
+ *
+ * @module api/iam/oauth2
+ */
+import { requestDatalayerAPI } from '../DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
+/**
+ * Get the OAuth2 authorization URL for a specific provider
+ * @param provider - OAuth2 provider (bluesky, github, linkedin, okta)
+ * @param callbackUri - Server endpoint to call with the authz token
+ * @param nonce - Optional nonce for security
+ * @param baseUrl - Base URL for the API (defaults to production IAM URL)
+ * @returns OAuth2 authorization URL response
+ * @throws {Error} If required parameters are missing or invalid
+ *
+ * @remarks
+ * This endpoint generates the OAuth2 authorization URL for the specified provider.
+ * Users should be redirected to the returned loginURL to begin the OAuth2 flow.
+ *
+ * Expected status codes:
+ * - 200: Successfully generated authorization URL
+ * - 400: Invalid parameters
+ * - 404: Provider not found or not configured
+ */
+export const getOAuth2AuthzUrl = async (provider, callbackUri, nonce, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    if (!provider) {
+        throw new Error('OAuth2 provider is required');
+    }
+    if (!callbackUri) {
+        throw new Error('Callback URI is required');
+    }
+    // Build query parameters
+    const queryParams = new URLSearchParams({
+        provider,
+        callback_uri: callbackUri,
+    });
+    if (nonce) {
+        queryParams.append('nonce', nonce);
+    }
+    try {
+        const response = await requestDatalayerAPI({
+            url: `${baseUrl}${API_BASE_PATHS.IAM}/oauth2/authz/url?${queryParams.toString()}`,
+            method: 'GET',
+        });
+        return response;
+    }
+    catch (error) {
+        // Check if it's a response error with status code information
+        if (error.response) {
+            const status = error.response.status;
+            // Expected errors
+            if (status === 400) {
+                throw new Error(`Invalid OAuth2 parameters: ${error.message}`);
+            }
+            if (status === 404) {
+                throw new Error(`OAuth2 provider '${provider}' not found or not configured`);
+            }
+            // Unexpected status codes
+            throw new Error(`Failed to get OAuth2 authorization URL: ${status} - ${error.message}`);
+        }
+        // Re-throw other errors (network errors, etc.)
+        throw error;
+    }
+};
+/**
+ * Get the OAuth2 authorization URL for linking a provider to an existing account
+ * @param provider - OAuth2 provider (bluesky, github, linkedin, okta)
+ * @param callbackUri - Server endpoint to call with the authz token
+ * @param baseUrl - Base URL for the API (defaults to production IAM URL)
+ * @returns OAuth2 authorization URL response
+ * @throws {Error} If required parameters are missing or invalid
+ *
+ * @remarks
+ * This endpoint generates the OAuth2 authorization URL for linking a provider to an existing account.
+ * Users should be redirected to the returned loginURL to begin the OAuth2 linking flow.
+ * This is different from the regular OAuth2 login flow as it links the provider to an existing account.
+ *
+ * Expected status codes:
+ * - 200: Successfully generated authorization URL
+ * - 400: Invalid parameters
+ * - 404: Provider not found or not configured
+ */
+export const getOAuth2AuthzUrlForLink = async (provider, callbackUri, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    if (!provider) {
+        throw new Error('OAuth2 provider is required');
+    }
+    if (!callbackUri) {
+        throw new Error('Callback URI is required');
+    }
+    // Build query parameters
+    const queryParams = new URLSearchParams({
+        provider,
+        callback_uri: callbackUri,
+    });
+    try {
+        const response = await requestDatalayerAPI({
+            url: `${baseUrl}${API_BASE_PATHS.IAM}/oauth2/authz/url/link?${queryParams.toString()}`,
+            method: 'GET',
+        });
+        return response;
+    }
+    catch (error) {
+        // Check if it's a response error with status code information
+        if (error.response) {
+            const status = error.response.status;
+            // Expected errors
+            if (status === 400) {
+                throw new Error(`Invalid OAuth2 link parameters: ${error.message}`);
+            }
+            if (status === 404) {
+                throw new Error(`OAuth2 provider '${provider}' not found or not configured for linking`);
+            }
+            // Unexpected status codes
+            throw new Error(`Failed to get OAuth2 link authorization URL: ${status} - ${error.message}`);
+        }
+        // Re-throw other errors (network errors, etc.)
+        throw error;
+    }
+};
+/**
+ * Handle GitHub OAuth2 callback
+ * @param params - OAuth2 callback parameters
+ * @param baseUrl - Base URL for the API (defaults to production IAM URL)
+ * @returns HTML response from the callback handler
+ * @throws {Error} If state parameter is missing
+ * @throws {Error} If the callback fails
+ *
+ * @remarks
+ * This endpoint handles the callback from GitHub after the user authorizes the application.
+ * It returns HTML content that typically includes JavaScript to handle the OAuth flow completion.
+ *
+ * Expected status codes:
+ * - 200: Callback processed successfully (returns HTML)
+ * - 403: Unauthorized
+ */
+export const handleGitHubOAuth2Callback = async (params, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    if (!params.state) {
+        throw new Error('State parameter is required for OAuth2 callback');
+    }
+    // Build query parameters
+    const queryParams = new URLSearchParams();
+    queryParams.append('state', params.state);
+    if (params.code) {
+        queryParams.append('code', params.code);
+    }
+    if (params.error) {
+        queryParams.append('error', params.error);
+    }
+    if (params.error_description) {
+        queryParams.append('error_description', params.error_description);
+    }
+    if (params.error_uri) {
+        queryParams.append('error_uri', params.error_uri);
+    }
+    try {
+        const response = await requestDatalayerAPI({
+            url: `${baseUrl}${API_BASE_PATHS.IAM}/oauth2/github/callback?${queryParams.toString()}`,
+            method: 'GET',
+            // Note: This endpoint returns HTML, not JSON
+            headers: {
+                Accept: 'text/html',
+            },
+        });
+        return response;
+    }
+    catch (error) {
+        // Check if it's a response error with status code information
+        if (error.response) {
+            const status = error.response.status;
+            // Expected errors
+            if (status === 403) {
+                throw new Error(`GitHub OAuth2 callback unauthorized: ${error.message}`);
+            }
+            // Unexpected status codes
+            throw new Error(`GitHub OAuth2 callback failed: ${status} - ${error.message}`);
+        }
+        // Re-throw other errors (network errors, etc.)
+        throw error;
+    }
+};
+/**
+ * Handle LinkedIn OAuth2 callback
+ * @param params - OAuth2 callback parameters
+ * @param baseUrl - Base URL for the API (defaults to production IAM URL)
+ * @returns HTML response from the callback handler
+ * @throws {Error} If state parameter is missing
+ * @throws {Error} If the callback fails
+ *
+ * @remarks
+ * This endpoint handles the callback from LinkedIn after the user authorizes the application.
+ * It returns HTML content that typically includes JavaScript to handle the OAuth flow completion.
+ *
+ * Expected status codes:
+ * - 200: Callback processed successfully (returns HTML)
+ * - 403: Unauthorized
+ */
+export const handleLinkedInOAuth2Callback = async (params, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    if (!params.state) {
+        throw new Error('State parameter is required for OAuth2 callback');
+    }
+    // Build query parameters
+    const queryParams = new URLSearchParams();
+    queryParams.append('state', params.state);
+    if (params.code) {
+        queryParams.append('code', params.code);
+    }
+    if (params.error) {
+        queryParams.append('error', params.error);
+    }
+    if (params.error_description) {
+        queryParams.append('error_description', params.error_description);
+    }
+    if (params.error_uri) {
+        queryParams.append('error_uri', params.error_uri);
+    }
+    try {
+        const response = await requestDatalayerAPI({
+            url: `${baseUrl}${API_BASE_PATHS.IAM}/oauth2/linkedin/callback?${queryParams.toString()}`,
+            method: 'GET',
+            // Note: This endpoint returns HTML, not JSON
+            headers: {
+                Accept: 'text/html',
+            },
+        });
+        return response;
+    }
+    catch (error) {
+        // Check if it's a response error with status code information
+        if (error.response) {
+            const status = error.response.status;
+            // Expected errors
+            if (status === 403) {
+                throw new Error(`LinkedIn OAuth2 callback unauthorized: ${error.message}`);
+            }
+            // Unexpected status codes
+            throw new Error(`LinkedIn OAuth2 callback failed: ${status} - ${error.message}`);
+        }
+        // Re-throw other errors (network errors, etc.)
+        throw error;
+    }
+};
+/**
+ * Handle Okta OAuth2 callback
+ * @param params - OAuth2 callback parameters
+ * @param baseUrl - Base URL for the API (defaults to production IAM URL)
+ * @returns HTML response from the callback handler
+ * @throws {Error} If state parameter is missing
+ * @throws {Error} If the callback fails
+ *
+ * @remarks
+ * This endpoint handles the callback from Okta after the user authorizes the application.
+ * It returns HTML content that typically includes JavaScript to handle the OAuth flow completion.
+ *
+ * Expected status codes:
+ * - 200: Callback processed successfully (returns HTML)
+ * - 403: Unauthorized
+ */
+export const handleOktaOAuth2Callback = async (params, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    if (!params.state) {
+        throw new Error('State parameter is required for OAuth2 callback');
+    }
+    // Build query parameters
+    const queryParams = new URLSearchParams();
+    queryParams.append('state', params.state);
+    if (params.code) {
+        queryParams.append('code', params.code);
+    }
+    if (params.error) {
+        queryParams.append('error', params.error);
+    }
+    if (params.error_description) {
+        queryParams.append('error_description', params.error_description);
+    }
+    if (params.error_uri) {
+        queryParams.append('error_uri', params.error_uri);
+    }
+    try {
+        const response = await requestDatalayerAPI({
+            url: `${baseUrl}${API_BASE_PATHS.IAM}/oauth2/okta/callback?${queryParams.toString()}`,
+            method: 'GET',
+            // Note: This endpoint returns HTML, not JSON
+            headers: {
+                Accept: 'text/html',
+            },
+        });
+        return response;
+    }
+    catch (error) {
+        // Check if it's a response error with status code information
+        if (error.response) {
+            const status = error.response.status;
+            // Expected errors
+            if (status === 403) {
+                throw new Error(`Okta OAuth2 callback unauthorized: ${error.message}`);
+            }
+            // Unexpected status codes
+            throw new Error(`Okta OAuth2 callback failed: ${status} - ${error.message}`);
+        }
+        // Re-throw other errors (network errors, etc.)
+        throw error;
+    }
+};

package/lib/api/iam/profile.d.ts

@@ -1,4 +1,4 @@
-import { UserMeResponse, WhoAmIResponse } from '../types/iam';
+import { MembershipsResponse, UserMeResponse, WhoAmIResponse } from '../types/iam';
 /**
  * Get current authenticated user profile
  * @param token - Authentication token (required)
@@ -13,3 +13,10 @@ export declare const me: (token: string, baseUrl?: string) => Promise<UserMeResp
  * @returns Current user identity and profile information
  */
 export declare const whoami: (token: string, baseUrl?: string) => Promise<WhoAmIResponse>;
+/**
+ * Get current user identity information
+ * @param token - Authentication token (required)
+ * @param baseUrl - Base URL for the API (defaults to production IAM URL)
+ * @returns Current user identity and profile information
+ */
+export declare const memberships: (token: string, baseUrl?: string) => Promise<MembershipsResponse>;

package/lib/api/iam/profile.js

@@ -3,10 +3,11 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/iam/profile
- * @description User profile management API functions for the Datalayer platform.
+ * User profile management API functions for the Datalayer platform.
  *
  * Provides functions for retrieving and managing user profile information.
+ *
+ * @module api/iam/profile
  */
 import { requestDatalayerAPI } from '../DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
@@ -39,3 +40,17 @@ export const whoami = async (token, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
         token,
     });
 };
+/**
+ * Get current user identity information
+ * @param token - Authentication token (required)
+ * @param baseUrl - Base URL for the API (defaults to production IAM URL)
+ * @returns Current user identity and profile information
+ */
+export const memberships = async (token, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.IAM}/memberships`,
+        method: 'GET',
+        token,
+    });
+};

package/lib/api/iam/usage.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Credit information for a user.
+ */
+export interface CreditsInfo {
+    /** Available credits */
+    credits: number;
+    /** Credit quota (null if unlimited) */
+    quota: number | null;
+    /** Last update timestamp */
+    last_update: string;
+}
+/**
+ * Credit reservation information.
+ */
+export interface CreditReservation {
+    /** Reservation ID */
+    id: string;
+    /** Reserved credits */
+    credits: number;
+    /** Resource ID (e.g., runtime ID) */
+    resource: string;
+    /** Last update timestamp */
+    last_update: string;
+    /** Burning rate (credits per hour) for this reservation */
+    burning_rate: number;
+    /** Start date of the reservation */
+    start_date: string;
+}
+/**
+ * Response from the credits endpoint.
+ */
+export interface CreditsResponse {
+    /** Operation success status */
+    success: boolean;
+    /** Credit information */
+    credits: CreditsInfo;
+    /** Active credit reservations */
+    reservations: CreditReservation[];
+}
+/**
+ * Get the current user's available credits and usage information.
+ *
+ * @param token - Authentication token
+ * @param iamUrl - Optional IAM service URL (defaults to production)
+ * @returns Promise with credits information
+ *
+ * @example
+ * ```typescript
+ * import { getCredits } from '@datalayer/core/api/iam';
+ *
+ * const creditsInfo = await getCredits(token);
+ * console.log(`Available credits: ${creditsInfo.credits.credits}`);
+ * console.log(`Quota: ${creditsInfo.credits.quota || 'unlimited'}`);
+ * ```
+ */
+export declare function getCredits(token: string, iamUrl?: string): Promise<CreditsResponse>;

package/lib/api/iam/usage.js

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Credits and usage API for managing user credits.
+ *
+ * Provides functionality to retrieve user's available credits, quota, and reservations.
+ *
+ * @module api/iam/credits
+ */
+import { requestDatalayerAPI } from '../DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
+/**
+ * Get the current user's available credits and usage information.
+ *
+ * @param token - Authentication token
+ * @param iamUrl - Optional IAM service URL (defaults to production)
+ * @returns Promise with credits information
+ *
+ * @example
+ * ```typescript
+ * import { getCredits } from '@datalayer/core/api/iam';
+ *
+ * const creditsInfo = await getCredits(token);
+ * console.log(`Available credits: ${creditsInfo.credits.credits}`);
+ * console.log(`Quota: ${creditsInfo.credits.quota || 'unlimited'}`);
+ * ```
+ */
+export async function getCredits(token, iamUrl = DEFAULT_SERVICE_URLS.IAM) {
+    return requestDatalayerAPI({
+        url: `${iamUrl}${API_BASE_PATHS.IAM}usage/credits`,
+        method: 'GET',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+        },
+    });
+}

package/lib/api/index.d.ts

@@ -1,9 +1,10 @@
 /**
- * @module @datalayer/core/api
- * @description Minimal API layer for the Datalayer platform providing base HTTP client and functional API methods.
+ * Minimal API layer for the Datalayer platform providing base HTTP client and functional API methods.
  *
  * This module contains the low-level API functionality. For high-level object-oriented
  * SDK classes, use @datalayer/core/sdk instead.
+ *
+ * @module @datalayer/core/api
  */
 export { requestDatalayerAPI, RunResponseError, NetworkError, } from './DatalayerApi';
 export type { IRequestDatalayerAPIOptions } from './DatalayerApi';
@@ -12,9 +13,9 @@ export * as iam from './iam';
 export * as runtimes from './runtimes';
 export * as spacer from './spacer';
 /**
- * @deprecated Please import directly from '@datalayer/core/sdk/stateful' instead.
+ * @deprecated Please import directly from '@datalayer/core/stateful' instead.
  * This module provides backward compatibility for the moved apiv1 modules.
  */
-export * from '../sdk/stateful/jupyter';
-export * from '../sdk/stateful/runtimes';
+export * from '../stateful/jupyter';
+export * from '../stateful/runtimes';
 export * from '../api/DatalayerApi';

package/lib/api/index.js

@@ -3,11 +3,12 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module @datalayer/core/api
- * @description Minimal API layer for the Datalayer platform providing base HTTP client and functional API methods.
+ * Minimal API layer for the Datalayer platform providing base HTTP client and functional API methods.
  *
  * This module contains the low-level API functionality. For high-level object-oriented
  * SDK classes, use @datalayer/core/sdk instead.
+ *
+ * @module @datalayer/core/api
  */
 // Base client exports
 export { requestDatalayerAPI, RunResponseError, NetworkError, } from './DatalayerApi';
@@ -18,9 +19,9 @@ export * as iam from './iam';
 export * as runtimes from './runtimes';
 export * as spacer from './spacer';
 /**
- * @deprecated Please import directly from '@datalayer/core/sdk/stateful' instead.
+ * @deprecated Please import directly from '@datalayer/core/stateful' instead.
  * This module provides backward compatibility for the moved apiv1 modules.
  */
-export * from '../sdk/stateful/jupyter';
-export * from '../sdk/stateful/runtimes';
+export * from '../stateful/jupyter';
+export * from '../stateful/runtimes';
 export * from '../api/DatalayerApi';

package/lib/api/runtimes/environments.js

@@ -3,10 +3,11 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/runtimes/environments
- * @description Computing environments API functions for the Datalayer platform.
+ * Computing environments API functions for the Datalayer platform.
  *
  * Provides functions for managing computing environment configurations.
+ *
+ * @module api/runtimes/environments
  */
 import { requestDatalayerAPI } from '../DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';

package/lib/api/runtimes/healthz.d.ts

@@ -1,25 +1,15 @@
-/**
- * Health check response from the Runtimes service
- */
-export interface RuntimesHealthzPingResponse {
-    success: boolean;
-    message: string;
-    status?: {
-        status: string;
-    };
-    version?: string;
-}
+import type { HealthzPingResponse } from '../types/common';
 /**
  * Health check ping endpoint for Runtimes service
  * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
  * @returns Health check response
  * @throws {Error} If the health check fails
  *
- * @description
+ * @remarks
  * This endpoint provides a basic health check for the Runtimes service.
  * It returns the current status of the service.
  *
  * Expected status codes:
  * - 200: Service is healthy
  */
-export declare const ping: (baseUrl?: string) => Promise<RuntimesHealthzPingResponse>;
+export declare const ping: (baseUrl?: string) => Promise<HealthzPingResponse>;

package/lib/api/runtimes/healthz.js

@@ -3,10 +3,11 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/runtimes/healthz
- * @description Health check API functions for the Datalayer Runtimes service.
+ * Health check API functions for the Datalayer Runtimes service.
  *
  * Provides functions for checking the health status of the Runtimes service.
+ *
+ * @module api/runtimes/healthz
  */
 import { requestDatalayerAPI } from '../DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
@@ -16,7 +17,7 @@ import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
  * @returns Health check response
  * @throws {Error} If the health check fails
  *
- * @description
+ * @remarks
  * This endpoint provides a basic health check for the Runtimes service.
  * It returns the current status of the service.
  *

package/lib/api/runtimes/index.d.ts

@@ -1,8 +1,9 @@
 /**
- * @module api/runtimes
- * @description Runtimes API exports.
+ * Runtimes API exports.
  *
  * Provides organized access to runtime management functionality.
+ *
+ * @module api/runtimes
  */
 export * as environments from './environments';
 export * as healthz from './healthz';

package/lib/api/runtimes/index.js

@@ -3,10 +3,11 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/runtimes
- * @description Runtimes API exports.
+ * Runtimes API exports.
  *
  * Provides organized access to runtime management functionality.
+ *
+ * @module api/runtimes
  */
 export * as environments from './environments';
 export * as healthz from './healthz';

package/lib/api/runtimes/runtimes.js

@@ -3,10 +3,11 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/runtimes/runtimes
- * @description Runtime instances API functions for the Datalayer platform.
+ * Runtime instances API functions for the Datalayer platform.
  *
  * Provides functions for managing runtime instances (active compute containers).
+ *
+ * @module api/runtimes/runtimes
  */
 import { requestDatalayerAPI } from '../DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
@@ -58,11 +59,14 @@ export const createRuntime = async (token, data, baseUrl = DEFAULT_SERVICE_URLS.
  */
 export const listRuntimes = async (token, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
     validateToken(token);
-    return requestDatalayerAPI({
+    const response = await requestDatalayerAPI({
         url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/runtimes`,
         method: 'GET',
         token,
     });
+    // The API returns { success: true, message: string, runtimes: Runtime[] }
+    // The response already has the correct structure, just return it
+    return response;
 };
 /**
  * Get details for a specific runtime instance.
@@ -83,10 +87,17 @@ export const getRuntime = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.
             method: 'GET',
             token,
         });
-        // The API returns { success: true, message: string, kernel: Runtime }
-        // We need to return just the runtime data
+        // The API returns { success: true, message: string, runtime: Runtime }
+        // (Previously used 'kernel' field, now uses 'runtime')
+        // Try 'runtime' field first (current API)
+        if (response.runtime) {
+            return {
+                ...response.runtime,
+                pod_name: response.runtime.pod_name || podName,
+            };
+        }
+        // Fallback to 'kernel' field (old API)
         if (response.kernel) {
-            // Map kernel fields to Runtime fields
             return {
                 ...response.kernel,
                 pod_name: response.kernel.pod_name || podName,

package/lib/api/runtimes/snapshots.js

@@ -3,10 +3,11 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/runtimes/snapshots
- * @description Runtime snapshots API functions for the Datalayer platform.
+ * Runtime snapshots API functions for the Datalayer platform.
  *
  * Provides functions for managing runtime snapshots (saved runtime states).
+ *
+ * @module api/runtimes/snapshots
  */
 import { requestDatalayerAPI } from '../DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';