@raisindb/functions-types 0.4.0 → 0.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raisindb/functions-types",
-  "version": "0.4.0",
+  "version": "0.4.5",
   "description": "TypeScript type definitions for the RaisinDB server-side function runtime (QuickJS)",
   "license": "MIT",
   "types": "raisin.d.ts",

package/raisin.d.ts

@@ -286,6 +286,20 @@ declare namespace raisin {
   namespace crypto {
     function uuid(): Promise<string>;
     function verifyJwt(token: string, opts?: any | null): Promise<any>;
+    /** n cryptographically secure random bytes, base64-encoded. n: 1..=64. */
+    function randomBytes(n: number): Promise<string>;
+    /** Lowercase hex digest. alg: "sha256" (default) | "sha512". */
+    function hash(input: string, alg?: string | null): Promise<string>;
+    /** Generate a signing keypair; alg defaults to "ES256" (ECDSA P-256). */
+    function generateKeyPair(
+      alg?: string | null
+    ): Promise<{ alg: string; publicJwk: any; privateJwk: any }>;
+    /** Sign claims into a compact JWS. Signature is JOSE r||s base64url. */
+    function signJwt(
+      claims: any,
+      privateJwk: any,
+      opts?: { alg?: string; kid?: string; expiresInSec?: number } | null
+    ): Promise<string>;
   }
 
   namespace date {
@@ -306,18 +320,130 @@ declare namespace raisin {
   interface EmailMessage {
     /** One recipient address, or several. */
     to: string | string[];
+    /** Carbon copy. Visible to every recipient. */
+    cc?: string | string[];
+    /**
+     * Blind carbon copy. Each address is invisible to every other recipient.
+     *
+     * Counted against the same 20-recipient cap as `to` and `cc`, and checked
+     * against the function's `email_policy` exactly like them — a blind copy
+     * is not a way around the allowlist.
+     */
+    bcc?: string | string[];
     subject: string;
     /** Plain-text body. Always required, even alongside `html`. */
     text: string;
     html?: string;
+    /**
+     * Files to attach. Each entry names exactly one source.
+     *
+     * Defaults: at most 20 attachments, 10 MiB each and 10 MiB in total once
+     * decoded. An operator can raise them per sender in `/config/email`.
+     */
+    attachments?: EmailAttachment[];
+    /**
+     * Which of the tenant's configured senders to send through, by name (see
+     * {@link email.providers}). Omit it for the tenant's default — which is
+     * what system mail such as the magic link uses.
+     *
+     * An unknown name REJECTS rather than falling back to the default: mail
+     * leaving through the wrong account is worse than mail not leaving.
+     */
+    provider?: string;
+  }
+
+  /** Fields every attachment shares, whatever its source. */
+  interface EmailAttachmentBase {
+    /**
+     * Name the recipient sees. Required for `content`; for a node reference
+     * the stored file name is used when omitted.
+     *
+     * Rejected rather than cleaned up if it carries a path separator or a
+     * control character.
+     */
+    filename?: string;
+    /**
+     * MIME type. Derived from the filename (or the stored resource) when
+     * omitted. `multipart/*` and `message/*` are refused — neither can be a
+     * single attachment.
+     */
+    contentType?: string;
+    /**
+     * Set this to EMBED the file in the HTML body instead of listing it as a
+     * download: reference it as `<img src="cid:the-value">`.
+     *
+     * Requires an `html` body. Works over `smtp` and `resend`; `brevo` has no
+     * Content-ID and REJECTS an inline attachment rather than sending one that
+     * would arrive broken.
+     */
+    contentId?: string;
+  }
+
+  /** Bytes the function already holds. */
+  interface EmailAttachmentContent extends EmailAttachmentBase {
+    /** Standard base64, or a `data:<type>;base64,...` URL. */
+    content: string;
+    filename: string;
+    node?: never;
   }
 
+  /**
+   * A file stored on a node, fetched by the server.
+   *
+   * Read with the FUNCTION's authority, not the caller's — a function running
+   * from a trigger or a schedule reads as system. Treat it exactly as you
+   * treat {@link nodes.get}.
+   */
+  interface EmailAttachmentNode extends EmailAttachmentBase {
+    /** Path of the node holding the file. */
+    node: string;
+    /** Workspace the node lives in. Required. */
+    workspace: string;
+    /** Property holding the file. Defaults to `"file"`. */
+    property?: string;
+    content?: never;
+  }
+
+  /**
+   * One attachment: inline bytes, or a node reference.
+   *
+   * In JavaScript a `Resource` (from `node.getResource('file')`) may be passed
+   * directly and is converted to a node reference for you.
+   */
+  type EmailAttachment = EmailAttachmentContent | EmailAttachmentNode;
+
   /** Proof that the provider accepted a message. Acceptance is not delivery. */
   interface EmailReceipt {
     /** The provider's message id — what a later bounce/webhook correlates to. */
     message_id: string;
-    /** The provider that issued it, e.g. "resend" or "brevo". */
+    /** The provider API that issued it: "resend", "brevo" or "smtp". */
+    provider: string;
+    /**
+     * The configured sender it went through. Answers "which of my accounts
+     * sent this", which `provider` alone cannot once a tenant has two entries
+     * on the same API.
+     */
+    sender: string;
+  }
+
+  /** One of the tenant's configured senders, as {@link email.providers} lists it. */
+  interface EmailProviderInfo {
+    /** The name {@link email.send} accepts in `provider`. */
+    name: string;
+    /** The provider API behind it: "resend", "brevo" or "smtp". */
     provider: string;
+    from_address: string;
+    /** A disabled sender cannot be selected, by name or as the default. */
+    enabled: boolean;
+    /** True for the one system mail goes through. */
+    default: boolean;
+  }
+
+  /** What {@link email.providers} returns. */
+  interface EmailProviders {
+    /** The tenant master switch — off means no sender works, however many exist. */
+    enabled: boolean;
+    providers: EmailProviderInfo[];
   }
 
   namespace email {
@@ -327,13 +453,66 @@ declare namespace raisin {
      * Every recipient must be allowed by the function's `email_policy`
      * (`{ enabled, allowed_recipients }` in its `.node.yaml`, matched against
      * the recipient DOMAIN); with no block declared the function cannot send,
-     * and one disallowed recipient rejects the whole message.
+     * and one disallowed recipient rejects the whole message. "Every
+     * recipient" includes `cc` and `bcc`.
      *
      * Also rejects when email is not configured or not enabled for the tenant,
      * when the function's `secret_policy` does not grant the credential the
      * config references, or when the provider refuses the message.
      */
     function send(message: EmailMessage): Promise<EmailReceipt>;
+
+    /**
+     * List the tenant's configured senders, so a function can discover the
+     * names `send` accepts rather than hardcoding one it cannot verify.
+     *
+     * Carries no credential and no `credential_ref`: a function that may send
+     * does not thereby get to enumerate the secret store. Gated on the same
+     * `email_policy` as {@link send} — a function that may not send has no use
+     * for the names.
+     */
+    function providers(): Promise<EmailProviders>;
+  }
+
+  /** A tenant auth identity — what a magic link or password check resolves to. */
+  interface Identity {
+    id: string;
+    email: string;
+    /** True only once the magic-link verify step has proven possession. */
+    email_verified: boolean;
+    display_name: string | null;
+    /** Whether the account has local (password) credentials. */
+    has_password: boolean;
+  }
+
+  interface IdentityPatch {
+    /** New address; trimmed and lowercased. Clears `email_verified`. */
+    email?: string;
+    /** New password. Gives a magic-link-only account local credentials. */
+    password?: string;
+    display_name?: string;
+  }
+
+  /**
+   * Tenant identities (the auth records, NOT `raisin:User` nodes).
+   *
+   * Gated by the function's `identity_policy: { enabled: true }` in its
+   * `.node.yaml`; with no block declared every call rejects with
+   * `[identities:policy_denied]`.
+   */
+  namespace identities {
+    /** Look up an identity by (case-insensitive) email. `null` when none. */
+    function findByEmail(email: string): Promise<Identity | null>;
+    /**
+     * Change an identity's email, password and/or display name.
+     *
+     * Rejects with `[identities:email_taken]` when another account already
+     * holds the new address, and with `[identities:invalid_patch]` for any
+     * other key — `email_verified` in particular cannot be set here: a rename
+     * proves typing, not possession. When the email changes, the bound
+     * `raisin:User` node's `email` property follows.
+     */
+    function update(id: string, patch: IdentityPatch): Promise<Identity>;
   }
 
   namespace events {