@diagonal-hq/cli 0.0.0-stage → 0.1.0

package/dist/workflow/index.d.ts

@@ -0,0 +1,22 @@
+import './console';
+export { HostError, WorkflowFailure, fail, validationError } from './errors';
+export { invoke, setTransport, type HostTransport } from './transport';
+export { transaction } from './transaction';
+export { data } from './data';
+export { mail, notification, sms } from './notifications';
+export { InputField, InputSchema, v, type ContentDocument, type ContentNode, type ContentOptions, type FileVisibility, type Infer, type InferInput, type InputFieldKind, type InputFieldSpec, type InputShape, type Money, type RecordScope } from './input';
+export { defineWorkflow, parseWorkflowInput, redirect, respond, validateWorkflowInput, type Identity, type InputErrors, type InputValidator, type RequestContext, type ScriptExecution, type WorkflowContext, type WorkflowDefinition, type WorkflowExecution } from './workflow';
+export * from './generated/capabilities';
+/** The embedding host selects its execution context through its supplied declarations. */
+export interface ScriptHostContext {
+}
+/** Declaration-merged by the generated workspace module with one entry per resource. */
+export interface WorkspaceResources {
+}
+/**
+ * Declaration-merged by the generated workspace module with one entry per notification type:
+ * its id, the unions of its template ids (all, email-enabled, and SMS-enabled), and the shape
+ * of its variables.
+ */
+export interface WorkspaceNotificationTypes {
+}

package/dist/workflow/input.d.ts

@@ -0,0 +1,168 @@
+import type { ResourceKey } from './data';
+/**
+ * A declared input field, as data. The compiler reads a workflow's input schema from its source
+ * and saves each field as a workflow input variable, so the platform validates a run's input
+ * against these rules before the script starts. The same data travels with the workflow at run
+ * time, where the SDK uses it to coerce string values to the declared types.
+ */
+export interface InputFieldSpec {
+    readonly kind: InputFieldKind;
+    readonly optional: boolean;
+    readonly nullable: boolean;
+    /** Validation rules in the platform's rule syntax, such as `min:1` or `regex:/^[a-z]+$/`. */
+    readonly rules: readonly string[];
+    readonly label?: string;
+    readonly description?: string;
+    /** `select`: the allowed values. */
+    readonly options?: readonly (string | number)[];
+    /** `list`: the item field. */
+    readonly items?: InputFieldSpec;
+    /** `object`: the nested fields. */
+    readonly fields?: Readonly<Record<string, InputFieldSpec>>;
+    /** `record` and `recordReference`: the resource whose definitions or records the value must match. */
+    readonly resource?: string;
+    /** `recordReference`: the records the ID can name. The platform default is `active`. */
+    readonly scope?: RecordScope;
+    /** `file`: the accepted MIME types. */
+    readonly accept?: readonly string[];
+    /** `file`: the visibility of the file. */
+    readonly visibility?: FileVisibility;
+    /** `content`: the formatting the document may use. */
+    readonly content?: ContentOptions;
+}
+/**
+ * A money value as the platform stores it. It is a type alias, not an interface, so that it is
+ * assignable to the open money objects of capability inputs such as `money.format`.
+ */
+export type Money = {
+    amount: number;
+    currency: string;
+};
+export type InputFieldKind = 'text' | 'email' | 'url' | 'uuid' | 'phone' | 'date' | 'datetime' | 'time' | 'timezone' | 'color' | 'number' | 'integer' | 'money' | 'boolean' | 'select' | 'list' | 'object' | 'record' | 'recordReference' | 'roleReference' | 'file' | 'content';
+/** The records a record ID can name: `active`, `archived` (deleted), or `activeOrArchived` (all). */
+export type RecordScope = 'active' | 'archived' | 'activeOrArchived';
+export type FileVisibility = 'public' | 'private';
+export interface ContentOptions {
+    /** `false` allows one paragraph only. The default is `true`. */
+    readonly multiLine?: boolean;
+    /** The marks the text may use. Each mark is allowed unless it is `false`. */
+    readonly extensions?: Readonly<Partial<Record<'bold' | 'italic' | 'strike' | 'underline' | 'link', boolean>>>;
+    /** The block nodes the document may use. Each node is allowed unless it is `false`. */
+    readonly allowedNodes?: Readonly<Partial<Record<'heading' | 'blockquote' | 'bulletList' | 'orderedList' | 'media', boolean>>>;
+}
+/** A rich text node in the platform's content format. */
+export interface ContentNode {
+    type: string;
+    attrs?: Record<string, unknown>;
+    content?: ContentNode[];
+    marks?: {
+        type: string;
+        attrs?: Record<string, unknown>;
+    }[];
+    text?: string;
+}
+/** A rich text document in the platform's content format. */
+export interface ContentDocument extends ContentNode {
+    type: 'doc';
+}
+/**
+ * One field of a workflow's input schema. `T` is the value type the handler receives; `O` is
+ * whether the key may be absent. Every modifier returns a new field, so a field can be shared.
+ */
+export declare class InputField<T, O extends boolean = false> {
+    readonly $spec: InputFieldSpec;
+    /** Phantom members that carry the static types; they hold no value at run time. */
+    readonly $value: T;
+    readonly $optional: O;
+    constructor($spec: InputFieldSpec);
+    /** The key may be absent. */
+    optional(): InputField<T | undefined, true>;
+    /** The value may be `null`. */
+    nullable(): InputField<T | null, O>;
+    /** At least `value`: a number's value, a text's length, or a list's item count. */
+    min(value: number): InputField<T, O>;
+    /** At most `value`: a number's value, a text's length, or a list's item count. */
+    max(value: number): InputField<T, O>;
+    /** Between `min` and `max`, inclusive, measured as for `min` and `max`. */
+    between(min: number, max: number): InputField<T, O>;
+    /** Exactly `value`, measured as for `min` and `max`. */
+    size(value: number): InputField<T, O>;
+    /** The text matches the pattern. */
+    regex(pattern: RegExp): InputField<T, O>;
+    /** Any other platform validation rule, such as `starts_with:INV-` or `after:today`. */
+    rule(rule: string): InputField<T, O>;
+    label(label: string): InputField<T, O>;
+    description(description: string): InputField<T, O>;
+}
+export type InputShape = Record<string, InputField<unknown, boolean>>;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** The value an input schema describes: optional fields become optional keys. */
+export type InferInput<S extends InputShape> = Simplify<{
+    [K in keyof S as S[K]['$optional'] extends true ? never : K]: S[K]['$value'];
+} & {
+    [K in keyof S as S[K]['$optional'] extends true ? K : never]?: S[K]['$value'];
+}>;
+/** The value a field or schema describes: `Infer<typeof Input>`. */
+export type Infer<F extends InputField<unknown, boolean>> = F['$value'];
+/** A workflow's input schema: the fields of an object. */
+export declare class InputSchema<S extends InputShape> extends InputField<InferInput<S>> {
+    readonly shape: S;
+    constructor(shape: S);
+}
+/** Builders for a workflow's input schema. */
+export declare const v: {
+    text: () => InputField<string, false>;
+    email: () => InputField<string, false>;
+    url: () => InputField<string, false>;
+    uuid: () => InputField<string, false>;
+    phone: () => InputField<string, false>;
+    /** A calendar date, `YYYY-MM-DD`. */
+    date: () => InputField<string, false>;
+    /** A date and time, ISO 8601. */
+    datetime: () => InputField<string, false>;
+    /** A time of day, `HH:MM`. */
+    time: () => InputField<string, false>;
+    timezone: () => InputField<string, false>;
+    color: () => InputField<string, false>;
+    number: () => InputField<number, false>;
+    integer: () => InputField<number, false>;
+    /** An amount of money: `amount` in the currency's minor units, such as cents, and the lowercase ISO 4217 `currency`. */
+    money: () => InputField<Money, false>;
+    boolean: () => InputField<boolean, false>;
+    /** One of `options`. */
+    select: <const V extends readonly (string | number)[]>(options: V) => InputField<V[number], false>;
+    /** A list whose items each satisfy `items`. */
+    list: <T>(items: InputField<T, boolean>) => InputField<Exclude<T, undefined>[], false>;
+    /** An object with the given fields. */
+    object: <S extends InputShape>(shape: S) => InputSchema<S>;
+    /**
+     * The field values of a record of `resource`, checked against that resource's field
+     * definitions: types, required fields, and each field's own rules.
+     */
+    record: <R extends ResourceKey>(resource: R) => InputField<Record<string, unknown>, false>;
+    /** The ID of an existing record of `resource`, in `scope`. */
+    recordReference: <R extends ResourceKey>(resource: R, options?: {
+        scope?: RecordScope;
+    }) => InputField<string, false>;
+    /** The ID of an existing role. */
+    roleReference: () => InputField<string, false>;
+    /**
+     * A file: the ID of an existing file, or the temporary path of an upload. A data call that
+     * writes the value to a file field of a record finalizes the upload.
+     */
+    file: (options?: {
+        accept?: readonly string[];
+        visibility?: FileVisibility;
+    }) => InputField<string, false>;
+    /** A rich text document with the formatting that `options` allows. */
+    content: (options?: ContentOptions) => InputField<ContentDocument, false>;
+};
+/**
+ * Converts the string forms a request carries (`"5"`, `"true"`) to the declared types. It runs
+ * after the platform validated the input against the same schema, so a value it cannot convert
+ * is left as it is.
+ */
+export declare function coerceInput(spec: InputFieldSpec, value: unknown): unknown;
+export {};

package/dist/workflow/notifications.d.ts

@@ -0,0 +1,47 @@
+import type { ResourceKey } from './data';
+import { type MailSendNotificationInput, type MailSendNotificationOutput, type NotificationSendBulkNotificationsInput, type NotificationSendBulkNotificationsOutput, type NotificationSendNotificationInput, type NotificationSetConsentInput, type NotificationSetConsentOutput, type SmsSendNotificationInput, type SmsSendNotificationOutput } from './generated/capabilities';
+import type { WorkspaceNotificationTypes } from './index';
+type Entry = WorkspaceNotificationTypes[keyof WorkspaceNotificationTypes];
+type Declared = [keyof WorkspaceNotificationTypes] extends [never] ? false : true;
+export type NotificationTypeKey = Declared extends true ? Entry extends {
+    id: infer I;
+} ? I : never : string;
+type EntryFor<T> = Extract<Entry, {
+    id: T;
+}>;
+/**
+ * The template ids of one notification type under `Channel`: every template, or only the
+ * templates with email or SMS on. Any string while the workspace declares no types.
+ */
+export type NotificationTemplateKey<T, Channel extends 'template' | 'emailTemplate' | 'smsTemplate' = 'template'> = Declared extends true ? (EntryFor<T> extends Record<Channel, infer K> ? K : never) : string;
+/** The variables one notification type declares; any dictionary while the workspace declares no types. */
+export type NotificationVariables<T> = Declared extends true ? EntryFor<T> extends {
+    variables: infer V;
+} ? V : never : Record<string, unknown>;
+type NotificationInput<I, T, Channel extends 'template' | 'emailTemplate' | 'smsTemplate' = 'template'> = Omit<I, 'notificationType' | 'notificationTemplate' | 'variables'> & {
+    notificationType: T;
+    notificationTemplate?: NotificationTemplateKey<T, Channel>;
+} & ({} extends NotificationVariables<T> ? {
+    variables?: NotificationVariables<T>;
+} : {
+    variables: NotificationVariables<T>;
+});
+export declare const mail: {
+    sendNotification: <T extends NotificationTypeKey>(input: NotificationInput<MailSendNotificationInput, T, "emailTemplate">) => Promise<MailSendNotificationOutput>;
+    search: (input: import("./index").MailSearchInput) => Promise<import("./index").MailSearchOutput>;
+    send: (input: import("./index").MailSendInput) => Promise<import("./index").MailSendOutput>;
+};
+export declare const notification: {
+    sendNotification: <T extends NotificationTypeKey>(input: NotificationInput<NotificationSendNotificationInput, T>) => Promise<boolean>;
+    sendBulkNotifications: <T extends NotificationTypeKey, R extends ResourceKey>(input: Omit<NotificationInput<NotificationSendBulkNotificationsInput, T>, "resource"> & {
+        resource: R;
+    }) => Promise<NotificationSendBulkNotificationsOutput>;
+    setConsent: <R extends ResourceKey>(input: Omit<NotificationSetConsentInput, "resource"> & {
+        resource: R;
+    }) => Promise<NotificationSetConsentOutput>;
+    send: (input: import("./index").NotificationSendInput) => Promise<import("./index").NotificationSendOutput>;
+};
+export declare const sms: {
+    sendNotification: <T extends NotificationTypeKey>(input: NotificationInput<SmsSendNotificationInput, T, "smsTemplate">) => Promise<SmsSendNotificationOutput>;
+};
+export {};

package/dist/workflow/serial-transaction-transport.d.ts

@@ -0,0 +1,10 @@
+import type { HostTransport } from './transport';
+export declare class SerialTransactionTransport implements HostTransport {
+    private readonly transport;
+    private pending;
+    private settled;
+    private transactionOpen;
+    private closing;
+    constructor(transport: HostTransport);
+    call(name: string, input: Record<string, unknown>): Promise<unknown>;
+}

package/dist/workflow/testing/index.d.ts

@@ -0,0 +1,26 @@
+import { type HostTransport } from '../transport';
+import { type InputValidator, type WorkflowContext, type WorkflowDefinition } from '../workflow';
+export declare class MockTransport implements HostTransport {
+    private readonly handlers;
+    readonly calls: Array<{
+        name: string;
+        input: unknown;
+    }>;
+    constructor(handlers: Partial<Record<string, (input: any) => unknown>>);
+    call(name: string, input: Record<string, unknown>): Promise<unknown>;
+}
+export declare function runWorkflow<I, O>(workflow: WorkflowDefinition<I, O>, input: I, options?: {
+    transport?: HostTransport;
+    context?: Omit<Partial<WorkflowContext>, 'execution'> & {
+        execution?: Partial<WorkflowContext['execution']>;
+    };
+    /** The module's `validateInput` export; it runs before the handler, as in the sandbox. */
+    validateInput?: InputValidator<I>;
+}): Promise<O>;
+export declare const fake: {
+    reset(): /*elided*/ any;
+    email: () => string;
+    name: () => string;
+    uuid: () => string;
+    number: (min?: number, max?: number) => number;
+};

package/dist/workflow/transaction.d.ts

@@ -0,0 +1 @@
+export declare function transaction<T>(fn: () => Promise<T>): Promise<T>;

package/dist/workflow/transport.d.ts

@@ -0,0 +1,5 @@
+export interface HostTransport {
+    call(name: string, input: Record<string, unknown>): Promise<unknown>;
+}
+export declare function setTransport(transport: HostTransport | null): void;
+export declare function invoke<T>(name: string, input: object): Promise<T>;

package/dist/workflow/workflow.d.ts

@@ -0,0 +1,103 @@
+import type { ScriptHostContext } from './index';
+import { type InferInput, type InputFieldSpec, type InputSchema, type InputShape } from './input';
+export interface Identity {
+    id: string;
+    resourceId: string;
+    email: string | null;
+    name: string | null;
+    permissions: string[];
+}
+export interface RequestContext {
+    method: string;
+    url: string;
+    params: Record<string, string>;
+    query: Record<string, unknown>;
+    body: Record<string, unknown>;
+    headers: Record<string, string>;
+}
+export interface ScriptExecution {
+    id: string;
+    kind: 'workflow' | 'embedded';
+    owner: {
+        type: string;
+        id: string;
+    };
+}
+export interface WorkflowExecution extends ScriptExecution {
+    kind: 'workflow';
+    workflowId: string;
+}
+export interface WorkflowContext {
+    user: Identity | null;
+    callingUser: Identity | null;
+    trigger: Record<string, unknown>;
+    request: RequestContext | null;
+    workspace: {
+        id: string;
+        timezone: string;
+    };
+    execution: ScriptHostContext extends {
+        embedded: true;
+    } ? ScriptExecution : WorkflowExecution;
+    now: string;
+}
+export interface WorkflowDefinition<I, O> {
+    readonly $diagonal: 'workflow';
+    /** The declared input schema, when the workflow has one. */
+    readonly input?: InputFieldSpec;
+    /** Runs the handler with input that {@link parseWorkflowInput} already converted. */
+    run(input: I, ctx: WorkflowContext): Promise<O>;
+}
+/**
+ * Converts a run's raw input to the declared types. A runner calls it once and passes the result
+ * to both `validateInput` and `run`, so the validator and the handler receive the same input.
+ */
+export declare function parseWorkflowInput<I>(workflow: WorkflowDefinition<I, unknown>, input: unknown): I;
+/**
+ * The errors an input validator reports, keyed by input field. A key outside the input's own fields
+ * (a nested path such as `tags.0`) is allowed; an empty or absent message means the field is valid.
+ */
+export type InputErrors<I> = Partial<Record<keyof I & string, string | string[]>> & Record<string, string | string[] | undefined>;
+/**
+ * The `validateInput` export a script may define beside its workflow. It runs before the handler
+ * with the same input and context; when it reports any error, the run ends with a 422 and those
+ * errors, and the handler does not run.
+ */
+export type InputValidator<I> = (input: I, ctx: WorkflowContext) => InputErrors<I> | void | Promise<InputErrors<I> | void>;
+/** Runs a script's input validator and ends the run with a validation error when it reports one. */
+export declare function validateWorkflowInput<I>(validator: InputValidator<I>, input: I, ctx: WorkflowContext): Promise<void>;
+type Handler<I, O> = (input: I, ctx: WorkflowContext) => Promise<O> | O;
+/**
+ * Declares a workflow. With an input schema first, the platform validates every run's input
+ * against it before the script starts, and the handler's `input` type comes from the schema.
+ */
+export declare function defineWorkflow<S extends InputShape, O = unknown>(input: InputSchema<S>, handler: Handler<InferInput<S>, O>): WorkflowDefinition<InferInput<S>, O>;
+export declare function defineWorkflow<I = Record<string, unknown>, O = unknown>(handler: Handler<I, O>): WorkflowDefinition<I, O>;
+export type ResponseOutput = {
+    $response_status: number;
+    $response_body: unknown;
+    $response_content_type: string;
+};
+export type RedirectType = 'internal' | 'external' | 'back';
+export type RedirectOutput = {
+    redirect_url: string;
+    redirect_type: RedirectType;
+    permanent: boolean;
+    success?: string;
+};
+export declare function respond(body: unknown, options?: {
+    status?: number;
+    contentType?: string;
+}): ResponseOutput;
+/**
+ * Builds the output of a graph `http.redirect` step, with the same `redirect_type` and
+ * `permanent` keys. Without a `type`, a path such as `/done` redirects as `internal`. Any other
+ * URL, including a protocol-relative `//host`, redirects as `external`, because an Inertia
+ * request cannot follow a plain redirect to another origin. A `back` redirect is never permanent.
+ */
+export declare function redirect(url: string, options?: {
+    success?: string;
+    type?: RedirectType;
+    permanent?: boolean;
+}): RedirectOutput;
+export {};

package/dist/workflow/workspace.d.ts

@@ -0,0 +1,3 @@
+export declare const resources: Record<string, string>;
+export declare const notificationTypes: Record<string, string>;
+export declare const notificationTemplates: Record<string, Record<string, string>>;

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@diagonal-hq/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The diagonal CLI and the configuration helpers for file-based Diagonal workspaces.",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Diagonal-HQ/diagonal.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "diagonal": "./bin/diagonal.mjs"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/diagonal.mjs",
+    "dist/cli.mjs",
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/globals.d.ts",
+    "dist/sdk-contract.d.ts",
+    "dist/workflow",
+    "LICENSE",
+    "README.md"
+  ]
+}