ucl-auth-api

v0.1.0

Published

3 months ago

Universal Context Layer (UCL) Auth API client for Node.js and browsers

0High
0Medium
0Low

fastn.ai

ucl api client typescript node browser

UCL Auth API Client (TypeScript)

Universal Context Layer Auth API client for browser and Node.js with a modular, extensible design.

Repository: https://github.com/fastnai/ucl-auth-api-node

Install

npm install ucl-auth-api
# or
yarn add ucl-auth-api

Quick Start

import { UclClient } from 'ucl-auth-api';

const ucl = new UclClient({
  workspaceId: 'ws_123',
  authToken: async () => '<your-token>',
  // baseUrl?: 'https://live.fastn.ai/api',
  // stage?: 'LIVE',
  // fetch?: customFetch
});

const res = await ucl.connectors.auth({
  connectorId: 'c789',
  // tenantId?: 't123',
  // orgId?: 'o001',
  // workspaceId?: 'override-org', // overrides orgId if provided
  // refresh?: false
});

console.log(res.auth);

Design

Modular: constants, types, fetch resolver, http client, config normalizer, and client surface.
Cross-environment: Uses global fetch when available; falls back to cross-fetch in Node.js.
Token providers: Pass a string token or an async function for on-demand refresh without recreating the client.
Stable HTTP: Centralized header construction and error handling.

API

`class UclClient`

Constructor:

new UclClient({
  workspaceId: string,
  authToken?: string | () => string | Promise<string>,
  baseUrl?: string,      // default: https://live.fastn.ai/api
  stage?: string,        // default: LIVE
  fetch?: typeof fetch   // optional custom fetch
})

Methods:

setAuthToken(tokenOrProvider) — update token or async provider at runtime.
setFetch(fetchLike) — override the fetch implementation.

Namespaces:

`connectors.auth(params)`

Input:

{
  connectorId: string;           // required
  tenantId?: string;              // optional → header x-fastn-space-tenantid
  orgId?: string;                 // optional
  workspaceId?: string;           // optional; if provided, overrides orgId
  refresh?: boolean;              // optional
}

Behavior:

Headers include x-fastn-space-id (from constructor), stage (default LIVE), x-fastn-custom-auth: true, and authorization (your token).
orgId resolution: use workspaceId (param) if provided; else orgId; else 'community'.
Response shape: { auth: { ... } } where auth carries OAuth fields like access_token, expires_in (when applicable) or connector-specific credentials.

Returns:

type AuthResponse = { auth: Record<string, unknown> };

Error Handling

Non-2xx responses throw Error('HTTP <status> <statusText>: <body>').
Missing auth token throws: authToken is required. Provide it in config or via setAuthToken().

Testing

This package ships with Jest tests. Run:

npm test

To run live E2E against your workspace, export envs (or create a local .env):

export UCL_E2E=1
export UCL_BASE_URL=https://live.fastn.ai
export UCL_WORKSPACE_ID=<your-workspace-id>
export UCL_AUTH_TOKEN='<your-token>'
export UCL_CONNECTOR_ID=<your-connector-id>
export UCL_ORG_ID=<your-org-id>
export UCL_REFRESH=false
export UCL_TENANT_ID=<your-tenant-id>

npm test

Contributing

Follow TypeScript strictness and naming best practices.
Keep modules focused and reusable. Avoid duplication.
Add/extend tests for new features.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme