@verne-software/sdk 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Verne Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,217 @@
+# Verne Software Node.js SDK
+
+[![npm version](https://img.shields.io/npm/v/@verne-software/sdk.svg)](https://npmjs.org/package/@verne-software/sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](#)
+
+The official Node.js and TypeScript library for the [Verne Nautilus](https://vernesoft.com) platform.
+
+> **Server-side only.** API keys carry full service access and must never be used in browser or client-side code.
+
+## Requirements
+
+Node.js 18 or later.
+
+## Installation
+
+```bash
+npm install @verne-software/sdk
+# or
+yarn add @verne-software/sdk
+# or
+pnpm add @verne-software/sdk
+```
+
+## Quick Start
+
+```ts
+import { Verne } from '@verne-software/sdk';
+
+const verne = new Verne({
+  relay: process.env.VERNE_RELAY_KEY,
+  gate:  process.env.VERNE_GATE_KEY,
+});
+```
+
+You can also instantiate services independently if you only need one:
+
+```ts
+import { Relay, Gate } from '@verne-software/sdk';
+
+const relay = new Relay({ apiKey: process.env.VERNE_RELAY_KEY });
+const gate  = new Gate({ apiKey: process.env.VERNE_GATE_KEY });
+```
+
+## Relay — Webhooks-as-a-Service
+
+Send events to all subscribed endpoints:
+
+```ts
+await verne.relay.messages.send({
+  event_type: 'user.created',
+  payload: { id: 'usr_123' },
+});
+```
+
+Optional parameters:
+
+```ts
+await verne.relay.messages.send({
+  event_type: 'order.placed',
+  payload: { order_id: '999' },
+  idempotency_key: 'evt_abc', // prevent duplicate delivery within 24h
+  channels: ['team-a'],       // restrict to specific endpoint channels
+});
+```
+
+List previously sent events:
+
+```ts
+const page = await verne.relay.messages.list({ limit: 20, event_type: 'user.created' });
+
+console.log(page.data);        // Message[]
+console.log(page.has_more);    // boolean
+console.log(page.next_cursor); // pass to the next call to paginate
+```
+
+## Gate — Auth-as-a-Service
+
+### Identity Management
+
+Manage your end-users. The `tenant_id` is automatically scoped to your API key.
+
+```ts
+// Create a user
+const identity = await verne.gate.identities.create({
+  schema_id: 'user',
+  traits: {
+    email: 'user@example.com',
+    custom_data: { role: 'editor' },
+  },
+  credentials: {
+    password: { config: { password: 'StrongPassword123!' } },
+  },
+  state: 'active',
+});
+
+// Get a user
+await verne.gate.identities.get(identity.id);
+
+// Update a user (JSON Patch — RFC 6902)
+await verne.gate.identities.patch(identity.id, [
+  { op: 'replace', path: '/traits/custom_data/role', value: 'admin' },
+]);
+
+// Delete a user
+await verne.gate.identities.delete(identity.id);
+
+// Activate / deactivate a user (an inactive user cannot log in)
+await verne.gate.identities.deactivate(identity.id);
+await verne.gate.identities.activate(identity.id);
+// …or set the state explicitly:
+await verne.gate.identities.setState(identity.id, 'inactive');
+
+// Resend the email verification link
+await verne.gate.identities.resendVerification(identity.id);
+```
+
+### Security Settings
+
+Read or replace the tenant's security settings (passwordless login, TOTP MFA):
+
+```ts
+const security = await verne.gate.settings.getSecurity();
+// security.passwordless_enabled, security.mfa_enabled
+
+// Both fields are required — the update is a full replacement, not a merge.
+await verne.gate.settings.updateSecurity({
+  passwordless_enabled: true,
+  mfa_enabled: false,
+});
+```
+
+### Access Tokens
+
+Exchange your long-lived API key for a short-lived access token:
+
+```ts
+const token = await verne.gate.tokens.create({
+  subject: 'usr_123',
+  scopes: ['gate.tokens.read'], // optional
+  ttl_seconds: 3600,            // optional, default 3600, max 86400
+});
+
+// token.access_token — attach to downstream requests
+// token.expires_at   — ISO 8601 expiry
+```
+
+Validate a token:
+
+```ts
+const info = await verne.gate.tokens.introspect(token.access_token);
+
+if (!info.active) {
+  // token is expired or invalid
+}
+```
+
+### Authorization
+
+Check whether a subject is allowed to perform an action:
+
+```ts
+const decision = await verne.gate.authorize({
+  subject: 'usr_123',
+  action: 'relay.messages.read',
+  resource: 'tenant:ten_001',
+});
+
+if (!decision.allowed) {
+  throw new Error('Forbidden');
+}
+```
+
+## Error Handling
+
+All API errors throw a `VerneAPIError` with structured fields:
+
+```ts
+import { VerneAPIError } from '@verne-software/sdk';
+
+try {
+  await verne.relay.messages.send({ event_type: 'ping', payload: {} });
+} catch (err) {
+  if (err instanceof VerneAPIError) {
+    console.error(err.code);      // e.g. 'invalid_payload', 'unauthorized'
+    console.error(err.status);    // HTTP status code
+    console.error(err.requestId); // include in support requests
+  }
+}
+```
+
+Network failures and timeouts throw a base `VerneError`.
+
+## Configuration
+
+Both `Verne` and the per-service clients accept an optional `timeoutMs` (default `30000`):
+
+```ts
+const verne = new Verne({
+  relay: process.env.VERNE_RELAY_KEY,
+  timeoutMs: 10_000,
+});
+```
+
+Individual requests can be cancelled with an `AbortSignal`:
+
+```ts
+const controller = new AbortController();
+
+await verne.relay.messages.send(
+  { event_type: 'ping', payload: {} },
+  { signal: controller.signal },
+);
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,421 @@
+/**
+ * Paginated response wrapper returned by list endpoints.
+ */
+interface Paginated<T> {
+    data: T[];
+    has_more: boolean;
+    next_cursor?: string;
+}
+/**
+ * Per-request options that can override client defaults.
+ */
+interface RequestOptions {
+    /** Abort signal to cancel the request. */
+    signal?: AbortSignal;
+    /** Request timeout in milliseconds. Overrides the client-level default. */
+    timeoutMs?: number;
+    /** Extra headers merged into the request. */
+    headers?: Record<string, string>;
+}
+/**
+ * Configuration for the unified Verne client.
+ * Each key corresponds to a service; only provide keys for the services you use.
+ */
+interface VerneConfig {
+    /** API key for the Relay (Webhooks-as-a-Service) service. Format: vrn_relay_<env>_<secret> */
+    relay?: string;
+    /** API key for the Gate (Auth-as-a-Service) service. Format: vrn_gate_<env>_<secret> */
+    gate?: string;
+    /** Base URL override. Defaults to https://api.vernesoft.com */
+    baseUrl?: string;
+    /** Default request timeout in milliseconds. Defaults to 30000. */
+    timeoutMs?: number;
+}
+/**
+ * Configuration for a single-service client (Relay or Gate).
+ */
+interface ServiceConfig {
+    /** API key for the service. */
+    apiKey: string;
+    /** Base URL override. Defaults to https://api.vernesoft.com */
+    baseUrl?: string;
+    /** Default request timeout in milliseconds. Defaults to 30000. */
+    timeoutMs?: number;
+}
+
+interface HttpClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+interface HttpRequestOptions extends RequestOptions {
+    /** When true, omit the Authorization header (used by gate.tokens.create). */
+    skipAuth?: boolean;
+    /** Body to send as JSON. */
+    body?: unknown;
+}
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(config: HttpClientConfig);
+    get<T>(path: string, options?: HttpRequestOptions): Promise<T>;
+    post<T>(path: string, options?: HttpRequestOptions): Promise<T>;
+    put<T>(path: string, options?: HttpRequestOptions): Promise<T>;
+    patch<T>(path: string, options?: HttpRequestOptions): Promise<T>;
+    delete<T>(path: string, options?: HttpRequestOptions): Promise<T>;
+    private request;
+}
+
+/** A Kratos identity managed by Gate. */
+interface Identity {
+    id: string;
+    schema_id: string;
+    state: 'active' | 'inactive';
+    traits: IdentityTraits;
+}
+interface IdentityTraits {
+    email: string;
+    tenant_id: string;
+    custom_data?: Record<string, unknown>;
+}
+/**
+ * Parameters for creating a new identity (end-user) bound to your tenant.
+ * The `traits.tenant_id` is injected automatically by the Edge Gateway.
+ */
+interface CreateIdentityParams {
+    /** Must be 'user'. */
+    schema_id: 'user';
+    traits: {
+        email: string;
+        /** Optional arbitrary fields for your application. */
+        custom_data?: Record<string, unknown>;
+    };
+    credentials?: {
+        password?: {
+            config: {
+                password: string;
+            };
+        };
+    };
+    state?: 'active' | 'inactive';
+}
+/**
+ * A single operation in a JSON Patch document (RFC 6902).
+ * Used by identities.patch() to partially update an identity.
+ */
+interface JsonPatchOp {
+    op: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
+    path: string;
+    value?: unknown;
+    from?: string;
+}
+/** Security-related Gate Identity settings for your tenant. */
+interface SecuritySettings {
+    /** Whether email-OTP (passwordless) login is enabled. */
+    passwordless_enabled: boolean;
+    /** Whether TOTP two-factor authentication is enabled. */
+    mfa_enabled: boolean;
+}
+/**
+ * A social login (OAuth 2.0 / OIDC) provider and whether it is enabled for
+ * your tenant's end-users.
+ */
+interface OidcProvider {
+    /** Provider identifier, e.g. `'github'`, `'google'`, `'gitlab'`. */
+    provider: string;
+    /** Whether the provider appears in your tenant's login/registration UI. */
+    enabled: boolean;
+}
+/**
+ * A Kratos self-service auth flow returned by {@link Gate.createLoginFlow}.
+ *
+ * The shape mirrors the raw Ory Kratos flow JSON (`ui.nodes`, `ui.action`,
+ * …); pass it straight to your browser-side code to render social buttons.
+ */
+type LoginFlow = Record<string, unknown>;
+/** Short-lived access token returned by tokens.create(). */
+interface AccessToken {
+    access_token: string;
+    expires_at: string;
+    subject: string;
+    tenant_id: string;
+}
+/** Parameters for exchanging an API key for a short-lived access token. */
+interface CreateTokenParams {
+    /** The ID of the user or service account this token represents. */
+    subject: string;
+    /** Optional list of scopes to narrow the token's permissions. */
+    scopes?: string[];
+    /** Custom lifetime in seconds. Default 3600, max 86400. */
+    ttl_seconds?: number;
+}
+/** Result of token introspection. */
+interface IntrospectResult {
+    active: boolean;
+    subject: string;
+    tenant_id: string;
+    scopes: string[];
+    expires_at: string;
+}
+/** Parameters for checking whether a subject can perform an action. */
+interface AuthorizeParams {
+    /** ID of the user or service account (e.g. 'usr_123'). */
+    subject: string;
+    /** Action being performed (e.g. 'relay.messages.read'). */
+    action: string;
+    /** Resource identifier (e.g. 'tenant:ten_001' or 'relay:key:key_123'). */
+    resource: string;
+    /** Optional extra attributes for policy evaluation. */
+    context?: Record<string, unknown>;
+}
+/** Authorization decision returned by gate.authorize(). */
+interface AuthorizeResult {
+    allowed: boolean;
+    decision_id: string;
+    reason: string;
+}
+
+declare class IdentitiesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Creates a new identity (end-user) bound to your tenant.
+     * The `traits.tenant_id` is injected automatically by the Edge Gateway.
+     */
+    create(params: CreateIdentityParams, options?: RequestOptions): Promise<Identity>;
+    /**
+     * Returns an identity by ID.
+     * The Gateway will reject the request if the identity does not belong to your tenant.
+     */
+    get(identityId: string, options?: RequestOptions): Promise<Identity>;
+    /**
+     * Partially updates an identity using a JSON Patch document (RFC 6902).
+     *
+     * @example
+     * await gate.identities.patch('identity_123', [
+     *   { op: 'replace', path: '/traits/custom_data/role', value: 'admin' }
+     * ]);
+     */
+    patch(identityId: string, ops: JsonPatchOp[], options?: RequestOptions): Promise<Identity>;
+    /**
+     * Deletes an identity from Kratos.
+     * The Gateway will reject the request if the identity does not belong to your tenant.
+     */
+    delete(identityId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Activates or deactivates an identity. An `inactive` identity cannot log in —
+     * Kratos rejects its credentials automatically — until it is reactivated.
+     * The identity is not deleted. Fires the `identity.state_changed` webhook event.
+     *
+     * @example
+     * await gate.identities.setState('identity_123', 'inactive');
+     */
+    setState(identityId: string, state: 'active' | 'inactive', options?: RequestOptions): Promise<Identity>;
+    /** Convenience wrapper for {@link setState}(identityId, 'active'). */
+    activate(identityId: string, options?: RequestOptions): Promise<Identity>;
+    /** Convenience wrapper for {@link setState}(identityId, 'inactive'). */
+    deactivate(identityId: string, options?: RequestOptions): Promise<Identity>;
+    /**
+     * Triggers a new email verification flow for an identity — useful when the
+     * original verification email expired or was never received. The user receives
+     * a fresh verification email. Resolves on `204 No Content`.
+     */
+    resendVerification(identityId: string, options?: RequestOptions): Promise<void>;
+}
+
+declare class SettingsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Returns the tenant's security settings (passwordless / MFA).
+     */
+    getSecurity(options?: RequestOptions): Promise<SecuritySettings>;
+    /**
+     * Replaces the tenant's security settings. Both fields are required — the
+     * update is a full replacement, not a merge.
+     *
+     * @example
+     * await gate.settings.updateSecurity({ passwordless_enabled: true, mfa_enabled: false });
+     */
+    updateSecurity(settings: SecuritySettings, options?: RequestOptions): Promise<void>;
+    /**
+     * Returns the tenant's social login (OIDC) providers and whether each is
+     * enabled. Covers all providers Gate supports, regardless of state.
+     */
+    getOidcProviders(options?: RequestOptions): Promise<OidcProvider[]>;
+    /**
+     * Sets the `enabled` flag for one or more social login providers. Any
+     * provider omitted from `providers` is left unchanged. Returns the full,
+     * updated provider list.
+     *
+     * @example
+     * await gate.settings.updateOidcProviders([
+     *   { provider: 'github', enabled: true },
+     *   { provider: 'google', enabled: true },
+     * ]);
+     */
+    updateOidcProviders(providers: OidcProvider[], options?: RequestOptions): Promise<OidcProvider[]>;
+}
+
+declare class TokensResource {
+    private readonly http;
+    private readonly apiKey;
+    constructor(http: HttpClient, apiKey: string);
+    /**
+     * Exchanges the Gate API key for a short-lived access token.
+     *
+     * Note: This endpoint does not use the Authorization header — the API key
+     * is passed in the request body per the Gate API specification.
+     */
+    create(params: CreateTokenParams, options?: RequestOptions): Promise<AccessToken>;
+    /**
+     * Validates a Gate access token and returns its decoded attributes.
+     */
+    introspect(accessToken: string, options?: RequestOptions): Promise<IntrospectResult>;
+}
+
+declare class Gate {
+    readonly identities: IdentitiesResource;
+    readonly tokens: TokensResource;
+    readonly settings: SettingsResource;
+    private readonly http;
+    constructor(config: ServiceConfig);
+    /**
+     * Checks whether a given subject is allowed to perform an action on a resource.
+     * This is the core building block for enforcing authorization in your services.
+     *
+     * @example
+     * const result = await gate.authorize({
+     *   subject: 'usr_123',
+     *   action: 'relay.messages.read',
+     *   resource: 'tenant:ten_001',
+     * });
+     * if (!result.allowed) throw new Error('Forbidden');
+     */
+    authorize(params: AuthorizeParams, options?: RequestOptions): Promise<AuthorizeResult>;
+    /**
+     * Returns the list of social login providers currently enabled for a tenant.
+     * This is a public, unauthenticated endpoint — call it from your login /
+     * registration page to decide which social buttons to render.
+     *
+     * @example
+     * const providers = await gate.getEnabledProviders('ten_001');
+     * // → ['github', 'google']
+     */
+    getEnabledProviders(tenantId: string, options?: RequestOptions): Promise<string[]>;
+    /**
+     * Initializes a Kratos login flow using your Gate API key. Call this from
+     * your server and pass the returned flow JSON to your browser-side code to
+     * render social login buttons. The flow already contains only the providers
+     * your tenant has enabled.
+     *
+     * @example
+     * const flow = await gate.createLoginFlow();
+     * // send `flow` to the browser as JSON
+     */
+    createLoginFlow(options?: RequestOptions): Promise<LoginFlow>;
+}
+
+/** A message (event) as returned by the Relay API. */
+interface Message {
+    /** Unique message identifier. */
+    id: string;
+    /** Dot-notated event name (e.g. 'user.created'). */
+    event_type: string;
+    /** Delivery status after being accepted by Relay. */
+    status: 'accepted';
+    /** ISO 8601 timestamp of when the event was accepted. */
+    timestamp: string;
+}
+/** Parameters for sending an event via Relay. */
+interface SendMessageParams {
+    /** Dot-notated event name (e.g. 'user.created'). */
+    event_type: string;
+    /** Arbitrary JSON payload delivered to subscribers. */
+    payload: Record<string, unknown>;
+    /**
+     * Optional idempotency key to prevent duplicate delivery within a 24-hour window.
+     * If a message with the same key was already accepted, a 409 is returned.
+     */
+    idempotency_key?: string;
+    /** Restrict delivery to endpoints listening on these channels. */
+    channels?: string[];
+}
+/** Query parameters for listing sent events. */
+interface ListMessagesParams {
+    /** Number of items per page. Max 100. Defaults to 20. */
+    limit?: number;
+    /** Pagination cursor from a previous response. */
+    cursor?: string;
+    /** Filter results by event type. */
+    event_type?: string;
+}
+/** Paginated list of messages returned by GET /v1/relay/messages. */
+type ListMessagesResponse = Paginated<Message>;
+
+declare class MessagesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Publish an event to all endpoints subscribed to the given event_type.
+     * Automatically retries once on 429 (respects Retry-After header).
+     *
+     * @returns The accepted message with its assigned ID and timestamp.
+     */
+    send(params: SendMessageParams, options?: RequestOptions): Promise<Message>;
+    /**
+     * Returns a paginated list of previously sent events for the current tenant.
+     */
+    list(params?: ListMessagesParams, options?: RequestOptions): Promise<ListMessagesResponse>;
+}
+
+declare class Relay {
+    readonly messages: MessagesResource;
+    constructor(config: ServiceConfig);
+}
+
+declare class Verne {
+    private readonly config;
+    private _relay?;
+    private _gate?;
+    constructor(config: VerneConfig);
+    get relay(): Relay;
+    get gate(): Gate;
+}
+
+/**
+ * Base class for all errors thrown by the Verne SDK.
+ */
+declare class VerneError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the Verne API returns an error response.
+ * Contains structured information from the API error envelope.
+ */
+declare class VerneAPIError extends VerneError {
+    /** Machine-readable error code (e.g. 'invalid_payload', 'unauthorized'). */
+    readonly code: string;
+    /** HTTP status code. */
+    readonly status: number;
+    /** Request ID to include when contacting support. */
+    readonly requestId: string;
+    constructor({ code, message, status, requestId, }: {
+        code: string;
+        message: string;
+        status: number;
+        requestId: string;
+    });
+    static fromResponse(status: number, body: APIErrorBody): VerneAPIError;
+}
+/** Shape of the API error envelope returned by all Verne services. */
+interface APIErrorBody {
+    error: {
+        code: string;
+        message: string;
+        request_id: string;
+    };
+}
+
+export { type APIErrorBody, type AccessToken, type AuthorizeParams, type AuthorizeResult, type CreateIdentityParams, type CreateTokenParams, Gate, type Identity, type IdentityTraits, type IntrospectResult, type JsonPatchOp, type ListMessagesParams, type ListMessagesResponse, type LoginFlow, type Message, type OidcProvider, type Paginated, Relay, type RequestOptions, type SecuritySettings, type SendMessageParams, type ServiceConfig, Verne, VerneAPIError, type VerneConfig, VerneError };