@verne-software/sdk 1.1.0 → 1.3.0

package/README.md

@@ -27,18 +27,20 @@ pnpm add @verne-software/sdk
 import { Verne } from '@verne-software/sdk';
 
 const verne = new Verne({
-  relay: process.env.VERNE_RELAY_KEY,
-  gate:  process.env.VERNE_GATE_KEY,
+  relay:     process.env.VERNE_RELAY_KEY,
+  gate:      process.env.VERNE_GATE_KEY,
+  clockwork: process.env.VERNE_CLOCKWORK_KEY,
 });
 ```
 
 You can also instantiate services independently if you only need one:
 
 ```ts
-import { Relay, Gate } from '@verne-software/sdk';
+import { Relay, Gate, Clockwork } from '@verne-software/sdk';
 
-const relay = new Relay({ apiKey: process.env.VERNE_RELAY_KEY });
-const gate  = new Gate({ apiKey: process.env.VERNE_GATE_KEY });
+const relay     = new Relay({ apiKey: process.env.VERNE_RELAY_KEY });
+const gate      = new Gate({ apiKey: process.env.VERNE_GATE_KEY });
+const clockwork = new Clockwork({ apiKey: process.env.VERNE_CLOCKWORK_KEY });
 ```
 
 ## Relay — Webhooks-as-a-Service
@@ -170,6 +172,58 @@ if (!decision.allowed) {
 }
 ```
 
+## Clockwork — Cron-as-a-Service
+
+Schedule recurring and one-shot HTTP jobs. The `tenant_id` is automatically scoped to your API key.
+
+### Cron Jobs
+
+```ts
+// Create a recurring job
+const job = await verne.clockwork.jobs.create({
+  name: 'nightly-report',
+  schedule: '0 2 * * *', // cron expression
+  url: 'https://example.com/hooks/report',
+  method: 'POST',                       // optional, defaults to POST
+  headers: { 'X-Api-Key': 'secret' },   // optional
+  body: JSON.stringify({ scope: 'all' }), // optional
+});
+
+// List all cron jobs (returns CronJob[])
+const jobs = await verne.clockwork.jobs.list();
+
+// Update a job (partial — only the fields you pass are changed)
+await verne.clockwork.jobs.update(job.id, { schedule: '0 3 * * *', is_active: false });
+
+// Inspect the execution history (returns Execution[])
+const runs = await verne.clockwork.jobs.executions(job.id);
+
+// Delete a job
+await verne.clockwork.jobs.delete(job.id);
+```
+
+### Delayed Jobs
+
+One-shot jobs that fire once at a specific time:
+
+```ts
+// Schedule a delayed job
+const delayed = await verne.clockwork.delayed.create({
+  name: 'send-reminder',
+  run_at: '2026-01-01T09:00:00Z', // ISO 8601 timestamp
+  url: 'https://example.com/hooks/reminder',
+});
+
+// List all delayed jobs (returns DelayedJob[])
+const pending = await verne.clockwork.delayed.list();
+
+// Inspect the execution history (returns Execution[])
+const runs = await verne.clockwork.delayed.executions(delayed.id);
+
+// Cancel a pending job
+await verne.clockwork.delayed.cancel(delayed.id);
+```
+
 ## Error Handling
 
 All API errors throw a `VerneAPIError` with structured fields:

package/dist/index.d.mts

@@ -26,6 +26,10 @@ interface VerneConfig {
     relay?: string;
     /** API key for the Gate (Auth-as-a-Service) service. Format: vrn_gate_<env>_<secret> */
     gate?: string;
+    /** API key for the Passepartout (Telegram Auth) service. Format: vrn_passepartout_<env>_<secret> */
+    passepartout?: string;
+    /** API key for the Clockwork (Cron-as-a-Service) service. Format: vrn_clockwork_<env>_<secret> */
+    clockwork?: string;
     /** Base URL override. Defaults to https://api.vernesoft.com */
     baseUrl?: string;
     /** Default request timeout in milliseconds. Defaults to 30000. */
@@ -67,6 +71,154 @@ declare class HttpClient {
     private request;
 }
 
+/** A recurring HTTP job scheduled on a cron expression. */
+interface CronJob {
+    id: string;
+    tenant_id: string;
+    name: string;
+    /** Cron expression, e.g. `'0 * * * *'` (hourly). */
+    schedule: string;
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body: string | null;
+    is_active: boolean;
+    last_run_at: string | null;
+    next_run_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** Parameters for creating a new cron job. */
+interface CreateCronJobParams {
+    name: string;
+    /** Cron expression, e.g. `'0 * * * *'` (hourly). */
+    schedule: string;
+    url: string;
+    /** HTTP method to invoke the target URL with. Defaults to `POST`. */
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+/**
+ * Parameters for updating an existing cron job. All fields are optional —
+ * only the fields you provide are changed.
+ */
+interface UpdateCronJobParams {
+    name?: string;
+    /** Cron expression, e.g. `'0 * * * *'` (hourly). */
+    schedule?: string;
+    url?: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    is_active?: boolean;
+}
+/** A one-shot HTTP job scheduled to run once at a specific time. */
+interface DelayedJob {
+    id: string;
+    tenant_id: string;
+    name: string;
+    /** ISO 8601 timestamp at which the job should fire. */
+    run_at: string;
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body: string | null;
+    status: string;
+    created_at: string;
+    updated_at: string;
+}
+/** Parameters for scheduling a new delayed job. */
+interface CreateDelayedJobParams {
+    name: string;
+    /** ISO 8601 timestamp at which the job should fire. */
+    run_at: string;
+    url: string;
+    /** HTTP method to invoke the target URL with. Defaults to `POST`. */
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+/** A single execution (run) of a cron or delayed job. */
+interface Execution {
+    id: string;
+    job_id: string;
+    status: string;
+    started_at: string;
+    completed_at: string | null;
+    duration_ms: number | null;
+    response_status: number | null;
+    response_body: string | null;
+    error_message: string | null;
+}
+
+declare class ClockworkDelayedResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Returns all delayed (one-shot) jobs for the current tenant.
+     */
+    list(options?: RequestOptions): Promise<DelayedJob[]>;
+    /**
+     * Schedules a new delayed job to run once at the given `run_at` time.
+     *
+     * @example
+     * const job = await clockwork.delayed.create({
+     *   name: 'send-reminder',
+     *   run_at: '2026-01-01T09:00:00Z',
+     *   url: 'https://example.com/hooks/reminder',
+     * });
+     */
+    create(params: CreateDelayedJobParams, options?: RequestOptions): Promise<DelayedJob>;
+    /**
+     * Cancels a pending delayed job. Resolves on `204 No Content`.
+     */
+    cancel(jobId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Returns the execution history for a delayed job.
+     */
+    executions(jobId: string, options?: RequestOptions): Promise<Execution[]>;
+}
+
+declare class ClockworkJobsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Returns all cron jobs for the current tenant.
+     */
+    list(options?: RequestOptions): Promise<CronJob[]>;
+    /**
+     * Creates a new recurring cron job.
+     *
+     * @example
+     * const job = await clockwork.jobs.create({
+     *   name: 'nightly-report',
+     *   schedule: '0 2 * * *',
+     *   url: 'https://example.com/hooks/report',
+     * });
+     */
+    create(params: CreateCronJobParams, options?: RequestOptions): Promise<CronJob>;
+    /**
+     * Partially updates an existing cron job. Only the fields you provide are changed.
+     */
+    update(jobId: string, params: UpdateCronJobParams, options?: RequestOptions): Promise<CronJob>;
+    /**
+     * Deletes a cron job. Resolves on `204 No Content`.
+     */
+    delete(jobId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Returns the execution history for a cron job (most recent runs first).
+     */
+    executions(jobId: string, options?: RequestOptions): Promise<Execution[]>;
+}
+
+declare class Clockwork {
+    readonly jobs: ClockworkJobsResource;
+    readonly delayed: ClockworkDelayedResource;
+    private readonly http;
+    constructor(config: ServiceConfig);
+}
+
 /** A Kratos identity managed by Gate. */
 interface Identity {
     id: string;
@@ -317,6 +469,76 @@ declare class Gate {
     createLoginFlow(options?: RequestOptions): Promise<LoginFlow>;
 }
 
+/** The Telegram end-user captured during login. */
+interface TelegramUser {
+    id: string;
+    username?: string;
+    first_name?: string;
+    photo_url?: string;
+}
+/** Response from starting a Telegram login. */
+interface LoginStart {
+    /** Opaque nonce identifying this login attempt. Poll `loginStatus(nonce)` with it. */
+    nonce: string;
+    /** `https://t.me/<bot>?start=<nonce>` — send the end-user here to authenticate. */
+    deep_link: string;
+    /** ISO-8601 timestamp after which the nonce expires. */
+    expires_at: string;
+}
+/** Current state of a Telegram login attempt. */
+interface LoginStatus {
+    /** `pending` until the user completes the Telegram flow, then `completed`. */
+    status: 'pending' | 'completed';
+    /** Present once completed — the end-user's access token. */
+    access_token?: string;
+    /** Present once completed — when the access token expires (ISO-8601). */
+    expires_at?: string;
+    /** Present once completed — the provisioned Kratos identity id. */
+    identity_id?: string;
+    /** Present once completed — the authenticated Telegram user. */
+    user?: TelegramUser;
+}
+/** Result of introspecting a Passepartout access token. */
+interface TokenIntrospection {
+    active: boolean;
+    subject?: string;
+    tenant_id?: string;
+    scopes?: string[];
+    expires_at?: string;
+}
+
+/**
+ * Verne Passepartout — Telegram Auth-as-a-Service.
+ *
+ * Lets your end-users sign in with Telegram: start a login to get a deep link,
+ * send the user to it, then poll for completion to receive an access token.
+ */
+declare class Passepartout {
+    private readonly http;
+    constructor(config: ServiceConfig);
+    /**
+     * Starts a Telegram login and returns a nonce + deep link. Send the user to
+     * `deep_link`, then poll {@link loginStatus} with `nonce` until it completes.
+     *
+     * @example
+     * const { nonce, deep_link } = await passepartout.loginStart();
+     * // redirect the user to `deep_link`, then poll:
+     * const status = await passepartout.loginStatus(nonce);
+     */
+    loginStart(options?: RequestOptions): Promise<LoginStart>;
+    /**
+     * Returns the current state of a login attempt. While the user hasn't
+     * finished, `status` is `pending`; once done it becomes `completed` and
+     * carries the `access_token` and `user`.
+     */
+    loginStatus(nonce: string, options?: RequestOptions): Promise<LoginStatus>;
+    /**
+     * Validates a Passepartout access token and returns its attributes.
+     * Tokens owned by another tenant are reported as `{ active: false }`.
+     */
+    introspect(accessToken: string, options?: RequestOptions): Promise<TokenIntrospection>;
+}
+
 /** A message (event) as returned by the Relay API. */
 interface Message {
     /** Unique message identifier. */
@@ -379,9 +601,13 @@ declare class Verne {
     private readonly config;
     private _relay?;
     private _gate?;
+    private _passepartout?;
+    private _clockwork?;
     constructor(config: VerneConfig);
     get relay(): Relay;
     get gate(): Gate;
+    get passepartout(): Passepartout;
+    get clockwork(): Clockwork;
 }
 
 /**
@@ -418,4 +644,4 @@ interface APIErrorBody {
     };
 }
 
-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 };
+export { type APIErrorBody, type AccessToken, type AuthorizeParams, type AuthorizeResult, Clockwork, type CreateCronJobParams, type CreateDelayedJobParams, type CreateIdentityParams, type CreateTokenParams, type CronJob, type DelayedJob, type Execution, Gate, type Identity, type IdentityTraits, type IntrospectResult, type JsonPatchOp, type ListMessagesParams, type ListMessagesResponse, type LoginFlow, type LoginStart, type LoginStatus, type Message, type OidcProvider, type Paginated, Passepartout, Relay, type RequestOptions, type SecuritySettings, type SendMessageParams, type ServiceConfig, type TelegramUser, type TokenIntrospection, type UpdateCronJobParams, Verne, VerneAPIError, type VerneConfig, VerneError };

package/dist/index.d.ts

@@ -26,6 +26,10 @@ interface VerneConfig {
     relay?: string;
     /** API key for the Gate (Auth-as-a-Service) service. Format: vrn_gate_<env>_<secret> */
     gate?: string;
+    /** API key for the Passepartout (Telegram Auth) service. Format: vrn_passepartout_<env>_<secret> */
+    passepartout?: string;
+    /** API key for the Clockwork (Cron-as-a-Service) service. Format: vrn_clockwork_<env>_<secret> */
+    clockwork?: string;
     /** Base URL override. Defaults to https://api.vernesoft.com */
     baseUrl?: string;
     /** Default request timeout in milliseconds. Defaults to 30000. */
@@ -67,6 +71,154 @@ declare class HttpClient {
     private request;
 }
 
+/** A recurring HTTP job scheduled on a cron expression. */
+interface CronJob {
+    id: string;
+    tenant_id: string;
+    name: string;
+    /** Cron expression, e.g. `'0 * * * *'` (hourly). */
+    schedule: string;
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body: string | null;
+    is_active: boolean;
+    last_run_at: string | null;
+    next_run_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** Parameters for creating a new cron job. */
+interface CreateCronJobParams {
+    name: string;
+    /** Cron expression, e.g. `'0 * * * *'` (hourly). */
+    schedule: string;
+    url: string;
+    /** HTTP method to invoke the target URL with. Defaults to `POST`. */
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+/**
+ * Parameters for updating an existing cron job. All fields are optional —
+ * only the fields you provide are changed.
+ */
+interface UpdateCronJobParams {
+    name?: string;
+    /** Cron expression, e.g. `'0 * * * *'` (hourly). */
+    schedule?: string;
+    url?: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    is_active?: boolean;
+}
+/** A one-shot HTTP job scheduled to run once at a specific time. */
+interface DelayedJob {
+    id: string;
+    tenant_id: string;
+    name: string;
+    /** ISO 8601 timestamp at which the job should fire. */
+    run_at: string;
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body: string | null;
+    status: string;
+    created_at: string;
+    updated_at: string;
+}
+/** Parameters for scheduling a new delayed job. */
+interface CreateDelayedJobParams {
+    name: string;
+    /** ISO 8601 timestamp at which the job should fire. */
+    run_at: string;
+    url: string;
+    /** HTTP method to invoke the target URL with. Defaults to `POST`. */
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+/** A single execution (run) of a cron or delayed job. */
+interface Execution {
+    id: string;
+    job_id: string;
+    status: string;
+    started_at: string;
+    completed_at: string | null;
+    duration_ms: number | null;
+    response_status: number | null;
+    response_body: string | null;
+    error_message: string | null;
+}
+
+declare class ClockworkDelayedResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Returns all delayed (one-shot) jobs for the current tenant.
+     */
+    list(options?: RequestOptions): Promise<DelayedJob[]>;
+    /**
+     * Schedules a new delayed job to run once at the given `run_at` time.
+     *
+     * @example
+     * const job = await clockwork.delayed.create({
+     *   name: 'send-reminder',
+     *   run_at: '2026-01-01T09:00:00Z',
+     *   url: 'https://example.com/hooks/reminder',
+     * });
+     */
+    create(params: CreateDelayedJobParams, options?: RequestOptions): Promise<DelayedJob>;
+    /**
+     * Cancels a pending delayed job. Resolves on `204 No Content`.
+     */
+    cancel(jobId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Returns the execution history for a delayed job.
+     */
+    executions(jobId: string, options?: RequestOptions): Promise<Execution[]>;
+}
+
+declare class ClockworkJobsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Returns all cron jobs for the current tenant.
+     */
+    list(options?: RequestOptions): Promise<CronJob[]>;
+    /**
+     * Creates a new recurring cron job.
+     *
+     * @example
+     * const job = await clockwork.jobs.create({
+     *   name: 'nightly-report',
+     *   schedule: '0 2 * * *',
+     *   url: 'https://example.com/hooks/report',
+     * });
+     */
+    create(params: CreateCronJobParams, options?: RequestOptions): Promise<CronJob>;
+    /**
+     * Partially updates an existing cron job. Only the fields you provide are changed.
+     */
+    update(jobId: string, params: UpdateCronJobParams, options?: RequestOptions): Promise<CronJob>;
+    /**
+     * Deletes a cron job. Resolves on `204 No Content`.
+     */
+    delete(jobId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Returns the execution history for a cron job (most recent runs first).
+     */
+    executions(jobId: string, options?: RequestOptions): Promise<Execution[]>;
+}
+
+declare class Clockwork {
+    readonly jobs: ClockworkJobsResource;
+    readonly delayed: ClockworkDelayedResource;
+    private readonly http;
+    constructor(config: ServiceConfig);
+}
+
 /** A Kratos identity managed by Gate. */
 interface Identity {
     id: string;
@@ -317,6 +469,76 @@ declare class Gate {
     createLoginFlow(options?: RequestOptions): Promise<LoginFlow>;
 }
 
+/** The Telegram end-user captured during login. */
+interface TelegramUser {
+    id: string;
+    username?: string;
+    first_name?: string;
+    photo_url?: string;
+}
+/** Response from starting a Telegram login. */
+interface LoginStart {
+    /** Opaque nonce identifying this login attempt. Poll `loginStatus(nonce)` with it. */
+    nonce: string;
+    /** `https://t.me/<bot>?start=<nonce>` — send the end-user here to authenticate. */
+    deep_link: string;
+    /** ISO-8601 timestamp after which the nonce expires. */
+    expires_at: string;
+}
+/** Current state of a Telegram login attempt. */
+interface LoginStatus {
+    /** `pending` until the user completes the Telegram flow, then `completed`. */
+    status: 'pending' | 'completed';
+    /** Present once completed — the end-user's access token. */
+    access_token?: string;
+    /** Present once completed — when the access token expires (ISO-8601). */
+    expires_at?: string;
+    /** Present once completed — the provisioned Kratos identity id. */
+    identity_id?: string;
+    /** Present once completed — the authenticated Telegram user. */
+    user?: TelegramUser;
+}
+/** Result of introspecting a Passepartout access token. */
+interface TokenIntrospection {
+    active: boolean;
+    subject?: string;
+    tenant_id?: string;
+    scopes?: string[];
+    expires_at?: string;
+}
+
+/**
+ * Verne Passepartout — Telegram Auth-as-a-Service.
+ *
+ * Lets your end-users sign in with Telegram: start a login to get a deep link,
+ * send the user to it, then poll for completion to receive an access token.
+ */
+declare class Passepartout {
+    private readonly http;
+    constructor(config: ServiceConfig);
+    /**
+     * Starts a Telegram login and returns a nonce + deep link. Send the user to
+     * `deep_link`, then poll {@link loginStatus} with `nonce` until it completes.
+     *
+     * @example
+     * const { nonce, deep_link } = await passepartout.loginStart();
+     * // redirect the user to `deep_link`, then poll:
+     * const status = await passepartout.loginStatus(nonce);
+     */
+    loginStart(options?: RequestOptions): Promise<LoginStart>;
+    /**
+     * Returns the current state of a login attempt. While the user hasn't
+     * finished, `status` is `pending`; once done it becomes `completed` and
+     * carries the `access_token` and `user`.
+     */
+    loginStatus(nonce: string, options?: RequestOptions): Promise<LoginStatus>;
+    /**
+     * Validates a Passepartout access token and returns its attributes.
+     * Tokens owned by another tenant are reported as `{ active: false }`.
+     */
+    introspect(accessToken: string, options?: RequestOptions): Promise<TokenIntrospection>;
+}
+
 /** A message (event) as returned by the Relay API. */
 interface Message {
     /** Unique message identifier. */
@@ -379,9 +601,13 @@ declare class Verne {
     private readonly config;
     private _relay?;
     private _gate?;
+    private _passepartout?;
+    private _clockwork?;
     constructor(config: VerneConfig);
     get relay(): Relay;
     get gate(): Gate;
+    get passepartout(): Passepartout;
+    get clockwork(): Clockwork;
 }
 
 /**
@@ -418,4 +644,4 @@ interface APIErrorBody {
     };
 }
 
-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 };
+export { type APIErrorBody, type AccessToken, type AuthorizeParams, type AuthorizeResult, Clockwork, type CreateCronJobParams, type CreateDelayedJobParams, type CreateIdentityParams, type CreateTokenParams, type CronJob, type DelayedJob, type Execution, Gate, type Identity, type IdentityTraits, type IntrospectResult, type JsonPatchOp, type ListMessagesParams, type ListMessagesResponse, type LoginFlow, type LoginStart, type LoginStatus, type Message, type OidcProvider, type Paginated, Passepartout, Relay, type RequestOptions, type SecuritySettings, type SendMessageParams, type ServiceConfig, type TelegramUser, type TokenIntrospection, type UpdateCronJobParams, Verne, VerneAPIError, type VerneConfig, VerneError };