@datalayer/core 0.0.12 → 0.0.13

package/README.md

@@ -81,7 +81,7 @@ npm install
 Set your Datalayer token as an environment variable:
 
 ```bash
-export DATALAYER_TOKEN="your-token-here"
+export DATALAYER_API_KEY="your-api-key"
 ```
 
 Or pass it directly to the SDK:
@@ -153,7 +153,7 @@ Run the interactive examples locally:
 npm install
 
 # Set your Datalayer API token in .env
-echo "VITE_DATALAYER_API_TOKEN=your-token-here" > .env
+echo "VITE_DATALAYER_API_KEY=your-token-here" > .env
 
 # Start the examples server
 npm run example

package/lib/api/DatalayerApi.d.ts

@@ -1,14 +1,14 @@
 /**
- * A wrapped error for a fetch response.
+ * Error wrapper for failed HTTP responses.
+ * Includes response details, warnings, errors, and tracebacks.
  */
 export declare class RunResponseError extends Error {
     /**
-     * Create a RunResponseError from a response,
-     * handling the traceback and message as appropriate.
+     * Creates a RunResponseError from a Response object.
+     * Extracts error details from response JSON.
      *
-     * @param response The response object.
-     *
-     * @returns A promise that resolves with a `RunResponseError` object.
+     * @param response - The failed HTTP response
+     * @returns Promise resolving to RunResponseError instance
      */
     static create(response: Response): Promise<RunResponseError>;
     /**
@@ -38,38 +38,50 @@ export declare class RunResponseError extends Error {
     private static _defaultMessage;
 }
 /**
- * A wrapped error for a network error.
+ * Error wrapper for network failures.
+ * Thrown when HTTP request fails due to connectivity issues.
  */
 export declare class NetworkError extends TypeError {
     /**
-     * Create a new network error.
+     * Creates a NetworkError from the original TypeError.
+     *
+     * @param original - The original network error
      */
     constructor(original: TypeError);
 }
+/**
+ * Options for Datalayer API requests.
+ */
 export interface IRequestDatalayerAPIOptions {
-    /**
-     * URL to request
-     */
+    /** Target URL for the request */
     url: string;
-    /**
-     * HTTP method
-     */
+    /** HTTP method (GET, POST, PUT, DELETE, etc.) */
     method?: string;
-    /**
-     * JSON-serializable object or FormData
-     */
+    /** Request body (JSON object or FormData) */
     body?: any;
-    /**
-     * Headers
-     */
+    /** Custom HTTP headers */
     headers?: Record<string, string>;
-    /**
-     * Authorization bearer token
-     */
+    /** JWT bearer token for authentication */
     token?: string;
-    /**
-     * Request abort signal.
-     */
+    /** AbortSignal for request cancellation */
     signal?: AbortSignal;
 }
+/**
+ * Makes authenticated HTTP requests to Datalayer APIs.
+ * Handles JSON and FormData, includes auth headers, and manages redirects.
+ *
+ * @param options - Request configuration
+ * @returns Promise resolving to response data
+ * @throws {NetworkError} On network failures
+ * @throws {RunResponseError} On HTTP error responses
+ *
+ * @example
+ * ```typescript
+ * const data = await requestDatalayerAPI({
+ *   url: 'https://api.datalayer.run/users',
+ *   method: 'GET',
+ *   token: 'eyJhbGc...'
+ * });
+ * ```
+ */
 export declare function requestDatalayerAPI<T = any>({ url, method, body, token, signal, headers, }: IRequestDatalayerAPIOptions): Promise<T>;

package/lib/api/DatalayerApi.js

@@ -2,20 +2,26 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+/**
+ * Core HTTP client for Datalayer API requests.
+ * Handles authentication, error handling, and async redirects.
+ *
+ * @module api/DatalayerApi
+ */
 import { URLExt } from '@jupyterlab/coreutils';
 import axios from 'axios';
 import { sleep } from '../utils/Sleep';
 /**
- * A wrapped error for a fetch response.
+ * Error wrapper for failed HTTP responses.
+ * Includes response details, warnings, errors, and tracebacks.
  */
 export class RunResponseError extends Error {
     /**
-     * Create a RunResponseError from a response,
-     * handling the traceback and message as appropriate.
-     *
-     * @param response The response object.
+     * Creates a RunResponseError from a Response object.
+     * Extracts error details from response JSON.
      *
-     * @returns A promise that resolves with a `RunResponseError` object.
+     * @param response - The failed HTTP response
+     * @returns Promise resolving to RunResponseError instance
      */
     static async create(response) {
         try {
@@ -69,11 +75,14 @@ export class RunResponseError extends Error {
     }
 }
 /**
- * A wrapped error for a network error.
+ * Error wrapper for network failures.
+ * Thrown when HTTP request fails due to connectivity issues.
  */
 export class NetworkError extends TypeError {
     /**
-     * Create a new network error.
+     * Creates a NetworkError from the original TypeError.
+     *
+     * @param original - The original network error
      */
     constructor(original) {
         super(original.message);
@@ -81,6 +90,24 @@ export class NetworkError extends TypeError {
         this.stack = original.stack;
     }
 }
+/**
+ * Makes authenticated HTTP requests to Datalayer APIs.
+ * Handles JSON and FormData, includes auth headers, and manages redirects.
+ *
+ * @param options - Request configuration
+ * @returns Promise resolving to response data
+ * @throws {NetworkError} On network failures
+ * @throws {RunResponseError} On HTTP error responses
+ *
+ * @example
+ * ```typescript
+ * const data = await requestDatalayerAPI({
+ *   url: 'https://api.datalayer.run/users',
+ *   method: 'GET',
+ *   token: 'eyJhbGc...'
+ * });
+ * ```
+ */
 export async function requestDatalayerAPI({ url, method, body, token, signal, headers = {}, }) {
     // Handle FormData differently from JSON
     const isFormData = body instanceof FormData;

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

@@ -1,6 +1,7 @@
 import { LoginRequest, LoginResponse } from '../types/iam';
 /**
  * Authenticate a user with credentials or token
+ *
  * @param data - Login credentials (either handle+password or token)
  * @param baseUrl - Base URL for the API (defaults to production IAM URL)
  * @returns Login response with tokens
@@ -9,7 +10,7 @@ import { LoginRequest, LoginResponse } from '../types/iam';
  * @throws {Error} If handle is provided without password or vice versa
  * @throws {Error} If server returns unexpected status code (expects 201 for success, 401 for failure)
  *
- * @description
+ * @remarks
  * Expected status codes:
  * - 201: Login succeeded
  * - 401: Login failed (invalid credentials)
@@ -23,18 +24,18 @@ export declare const login: (data: LoginRequest, baseUrl?: string) => Promise<Lo
  */
 export declare const logout: (token: string, baseUrl?: string) => Promise<void>;
 /**
- * Validate authentication through proxy
+ * Check authentication status
+ *
  * @param token - Authentication token (required)
  * @param baseUrl - Base URL for the API (defaults to production IAM URL)
- * @returns Promise that resolves if authenticated (200), rejects if unauthorized (401) or forbidden (403)
+ * @returns Promise that resolves if authenticated (200), rejects if unauthorized (401)
  * @throws {Error} If authentication token is missing or invalid
  *
- * @description
- * This endpoint validates authentication status through a proxy.
+ * @remarks
+ * This endpoint checks authentication status, useful for reverse proxy validation.
  *
  * Expected status codes:
  * - 200: Authenticated successfully
  * - 401: Unauthorized - invalid or missing credentials
- * - 403: Forbidden - valid credentials but access denied
  */
-export declare const proxyAuth: (token: string, baseUrl?: string) => Promise<void>;
+export declare const checkAuth: (token: string, baseUrl?: string) => Promise<void>;

package/lib/api/iam/authentication.js

@@ -3,16 +3,18 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/iam/authentication
- * @description Authentication API functions for the Datalayer platform.
+ * Authentication API functions for the Datalayer platform.
  *
  * Provides functions for user login, logout, and authentication management.
+ *
+ * @module api/iam/authentication
  */
 import { requestDatalayerAPI } from '../DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
 import { validateToken } from '../utils/validation';
 /**
  * Authenticate a user with credentials or token
+ *
  * @param data - Login credentials (either handle+password or token)
  * @param baseUrl - Base URL for the API (defaults to production IAM URL)
  * @returns Login response with tokens
@@ -21,7 +23,7 @@ import { validateToken } from '../utils/validation';
  * @throws {Error} If handle is provided without password or vice versa
  * @throws {Error} If server returns unexpected status code (expects 201 for success, 401 for failure)
  *
- * @description
+ * @remarks
  * Expected status codes:
  * - 201: Login succeeded
  * - 401: Login failed (invalid credentials)
@@ -82,25 +84,25 @@ export const logout = async (token, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
     });
 };
 /**
- * Validate authentication through proxy
+ * Check authentication status
+ *
  * @param token - Authentication token (required)
  * @param baseUrl - Base URL for the API (defaults to production IAM URL)
- * @returns Promise that resolves if authenticated (200), rejects if unauthorized (401) or forbidden (403)
+ * @returns Promise that resolves if authenticated (200), rejects if unauthorized (401)
  * @throws {Error} If authentication token is missing or invalid
  *
- * @description
- * This endpoint validates authentication status through a proxy.
+ * @remarks
+ * This endpoint checks authentication status, useful for reverse proxy validation.
  *
  * Expected status codes:
  * - 200: Authenticated successfully
  * - 401: Unauthorized - invalid or missing credentials
- * - 403: Forbidden - valid credentials but access denied
  */
-export const proxyAuth = async (token, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+export const checkAuth = async (token, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
     validateToken(token);
     try {
         const response = await requestDatalayerAPI({
-            url: `${baseUrl}${API_BASE_PATHS.IAM}/proxy-auth`,
+            url: `${baseUrl}${API_BASE_PATHS.IAM}/auth`,
             method: 'GET',
             token,
         });
@@ -114,13 +116,10 @@ export const proxyAuth = async (token, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
             const status = error.response.status;
             // Expected errors
             if (status === 401) {
-                throw new Error(`Proxy authentication failed: Unauthorized (${status})`);
-            }
-            if (status === 403) {
-                throw new Error(`Proxy authentication failed: Forbidden (${status})`);
+                throw new Error(`Authentication check failed: Unauthorized (${status})`);
             }
             // Unexpected status codes
-            throw new Error(`Proxy authentication failed: Unexpected status code ${status} - ${error.message}`);
+            throw new Error(`Authentication check failed: Unexpected status code ${status} - ${error.message}`);
         }
         // Re-throw other errors (network errors, etc.)
         throw error;

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

@@ -1,11 +1,12 @@
-import { HealthzPingResponse } from '../types/iam';
+import type { HealthzPingResponse } from '../types/common';
 /**
  * Health check ping endpoint
+ *
  * @param baseUrl - Base URL for the API (defaults to production IAM URL)
  * @returns Health check response with user count
  * @throws {Error} If the health check fails
  *
- * @description
+ * @remarks
  * This endpoint provides a basic health check for the IAM service.
  * It returns the current user count in the system.
  *

package/lib/api/iam/healthz.js

@@ -3,20 +3,22 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/iam/healthz
- * @description Health check API functions for the Datalayer IAM service.
+ * Health check API functions for the Datalayer IAM service.
  *
  * Provides functions for checking the health status of the IAM service.
+ *
+ * @module api/iam/healthz
  */
 import { requestDatalayerAPI } from '../DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
 /**
  * Health check ping endpoint
+ *
  * @param baseUrl - Base URL for the API (defaults to production IAM URL)
  * @returns Health check response with user count
  * @throws {Error} If the health check fails
  *
- * @description
+ * @remarks
  * This endpoint provides a basic health check for the IAM service.
  * It returns the current user count in the system.
  *

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

@@ -1,12 +1,17 @@
 /**
- * @module api/iam
- * @description IAM (Identity and Access Management) API exports.
+ * IAM (Identity and Access Management) API exports.
+ *
+ * Provides organized access to authentication, OAuth2, and user profile functionality.
  *
- * Provides organized access to authentication and user profile functionality.
+ * @module api/iam
  */
 export * as authentication from './authentication';
+export * as oauth2 from './oauth2';
 export * as profile from './profile';
 export * as healthz from './healthz';
-export { login, logout, proxyAuth } from './authentication';
+export * as usage from './usage';
+export { login, logout, checkAuth } from './authentication';
+export { getOAuth2AuthzUrl, getOAuth2AuthzUrlForLink, handleGitHubOAuth2Callback, handleLinkedInOAuth2Callback, handleOktaOAuth2Callback, type OAuth2Provider, type OAuth2AuthzUrlResponse, type OAuth2CallbackParams, type OAuth2CallbackResponse, } from './oauth2';
 export { me, whoami } from './profile';
 export { ping } from './healthz';
+export { getCredits, type CreditsInfo, type CreditReservation, type CreditsResponse, } from './usage';

package/lib/api/iam/index.js

@@ -3,15 +3,20 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * @module api/iam
- * @description IAM (Identity and Access Management) API exports.
+ * IAM (Identity and Access Management) API exports.
+ *
+ * Provides organized access to authentication, OAuth2, and user profile functionality.
  *
- * Provides organized access to authentication and user profile functionality.
+ * @module api/iam
  */
 export * as authentication from './authentication';
+export * as oauth2 from './oauth2';
 export * as profile from './profile';
 export * as healthz from './healthz';
+export * as usage from './usage';
 // For backward compatibility, export the old API structure
-export { login, logout, proxyAuth } from './authentication';
+export { login, logout, checkAuth } from './authentication';
+export { getOAuth2AuthzUrl, getOAuth2AuthzUrlForLink, handleGitHubOAuth2Callback, handleLinkedInOAuth2Callback, handleOktaOAuth2Callback, } from './oauth2';
 export { me, whoami } from './profile';
 export { ping } from './healthz';
+export { getCredits, } from './usage';

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

@@ -0,0 +1,115 @@
+/**
+ * OAuth2 provider types supported by the platform
+ */
+export type OAuth2Provider = 'github' | 'linkedin' | 'okta';
+/**
+ * Response from the OAuth2 authorization URL endpoint
+ */
+export interface OAuth2AuthzUrlResponse {
+    success: boolean;
+    message: string;
+    loginURL: string;
+}
+/**
+ * OAuth2 callback parameters
+ */
+export interface OAuth2CallbackParams {
+    code?: string;
+    state: string;
+    error?: string;
+    error_description?: string;
+    error_uri?: string;
+}
+/**
+ * OAuth2 callback response (HTML content)
+ */
+export type OAuth2CallbackResponse = string;
+/**
+ * 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 declare const getOAuth2AuthzUrl: (provider: OAuth2Provider, callbackUri: string, nonce?: string, baseUrl?: string) => Promise<OAuth2AuthzUrlResponse>;
+/**
+ * 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 declare const getOAuth2AuthzUrlForLink: (provider: OAuth2Provider, callbackUri: string, baseUrl?: string) => Promise<OAuth2AuthzUrlResponse>;
+/**
+ * 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 declare const handleGitHubOAuth2Callback: (params: OAuth2CallbackParams, baseUrl?: string) => Promise<OAuth2CallbackResponse>;
+/**
+ * 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 declare const handleLinkedInOAuth2Callback: (params: OAuth2CallbackParams, baseUrl?: string) => Promise<OAuth2CallbackResponse>;
+/**
+ * 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 declare const handleOktaOAuth2Callback: (params: OAuth2CallbackParams, baseUrl?: string) => Promise<OAuth2CallbackResponse>;