@vibiz/app 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -6,6 +6,9 @@
  *   await vibiz.email.send({ to, subject, text });
  *   await vibiz.user(userId).track('Upgraded', { properties: { plan: 'pro' } });
  *   const openai = new OpenAI(vibiz.ai);         // the AI gateway, OpenAI-compatible
+ *   const { url } = await vibiz.files.upload(bytes, { name: 'avatar.png' });
+ *   await vibiz.contacts.upsert({ email, first_name, lists: ['Users'] }); // newsletters, onboarding
+ *   await vibiz.contacts.track(email, 'upgraded', { plan: 'pro' });     // starts automations
  *
  * The key (`VIBIZ_APP_KEY`, `vz_app_…`) belongs to one project and one
  * environment. It is a server secret: this client refuses to run in a
@@ -45,6 +48,8 @@ export interface SendEmail {
 export interface ActionResult<O> {
     output: O;
     cost_micro_usd: number | null;
+    /** The run in the project's web data history (console ▸ Web data). */
+    run_id?: string;
 }
 export interface ChatMessage {
     role: 'system' | 'user' | 'assistant' | 'tool';
@@ -76,6 +81,8 @@ export interface Payment {
         brand: string;
         last4: string;
     } | null;
+    /** `own`: charged on the owner's own Stripe account (docs/PAYMENTS.md "Your own account"). */
+    account: 'vibiz' | 'own';
     dispute: {
         status: 'needs_response' | 'under_review' | 'won' | 'lost';
         amount_cents: number;
@@ -91,6 +98,8 @@ export interface Subscription {
     user: string | null;
     customer_email: string | null;
     price_id: string | null;
+    /** `own`: billed on the owner's own Stripe account. The app's code is the same either way. */
+    account: 'vibiz' | 'own';
     current_period_end: string | null;
     cancel_at_period_end: boolean;
     created_at: string;
@@ -191,9 +200,87 @@ export interface WebhookEvent<T = unknown> {
  * Pass the raw body, exactly as received. Throws on anything wrong.
  */
 export declare function verifyWebhook<T = unknown>(rawBody: string, header: string | null | undefined, secret?: string | undefined, nowSeconds?: number): WebhookEvent<T>;
+/** Someone the project emails: newsletters, announcements, automations (docs: email). */
+export interface ContactInput {
+    email: string;
+    first_name?: string | null;
+    last_name?: string | null;
+    /** Merged into what is stored; `null` removes a key. Use them in emails ({{plan|free}}) and segments. */
+    properties?: Record<string, string | number | boolean | null>;
+    /** List ids or names; a name that doesn't exist yet is created. */
+    lists?: string[];
+    /** `false` unsubscribes (from `lists` if given, else from everything). */
+    subscribed?: boolean;
+    /** Send a confirmation email first; they're `pending` until they click it. */
+    double_opt_in?: boolean;
+    /** How they agreed, kept as the record: method (`app_signup`), the words, IP, user agent. */
+    consent?: {
+        method?: string;
+        text?: string;
+        ip?: string;
+        user_agent?: string;
+        at?: string;
+    };
+}
+export interface Contact {
+    object: 'contact';
+    id: string;
+    email: string;
+    first_name: string | null;
+    last_name: string | null;
+    properties: Record<string, unknown>;
+    status: 'subscribed' | 'pending' | 'unsubscribed' | 'bounced' | 'complained' | 'dormant';
+    lists?: Array<{
+        id: string;
+        name: string;
+        status: 'subscribed' | 'unsubscribed';
+    }>;
+    created_at: string;
+    /** Development keys never touch the real list: `false` there, and nothing is stored. */
+    recorded?: false;
+    /** Bounced or marked mail as spam before: gets no marketing email. */
+    suppressed?: true;
+    confirmation_sent?: true;
+}
+/** A file in the project's Files (docs: files). */
+export interface AppFile {
+    object: 'file';
+    id: string;
+    project_id: string;
+    environment: 'production' | 'development';
+    name: string;
+    folder: string | null;
+    content_type: string;
+    kind: 'image' | 'video' | 'audio' | 'other';
+    size: number;
+    sha256: string;
+    source: 'upload' | 'ai';
+    private: boolean;
+    /** Permanent for public files; a signed link valid one hour for private ones. */
+    url: string;
+    url_expires_at: string | null;
+    /** Images; null otherwise or unknown. */
+    width: number | null;
+    height: number | null;
+    /** Video and audio; null when unknown. */
+    duration_seconds: number | null;
+    tags: string[];
+    note: string | null;
+    ai: {
+        model: string;
+        prompt: string;
+        cost_usd: number;
+        call_id: string | null;
+    } | null;
+    created_at: string;
+}
 export declare class VibizApp {
     private readonly options;
     private loaded;
+    /** When `webhooks.receive` last fetched the signing secret again. */
+    private secretRefreshedAt;
+    /** The signing secret as Vibiz last gave it to `webhooks.receive`. */
+    private webhookSecret;
     constructor(options?: VibizAppOptions);
     /** The key, read when first needed, so `loadEnv()` or a late env still works. */
     private get key();
@@ -251,7 +338,11 @@ export declare class VibizApp {
             status: string;
         }>>;
     };
-    /** Any action (`web.scrape`, `web.search`, `places.search`, `email.send`…), billed to the project. */
+    /**
+     * Any action, billed to the project: web data (`web.scrape`, `web.search`, `web.crawl`,
+     * `web.screenshot`, `web.design`, `ads.library`, `places.search`, `reviews`, `social.profile`,
+     * `social.posts`, `ecommerce.product`, `linkedin.company`) or `email.send`.
+     */
     readonly actions: {
         run: <O = unknown>(name: string, input: unknown) => Promise<ActionResult<O>>;
     };
@@ -309,9 +400,97 @@ export declare class VibizApp {
             body?: unknown;
         }) => Promise<ConnectorResponse<T>>;
     };
-    /** Webhooks from Vibiz: `verify(rawBody, header)` checks the signature with VIBIZ_WEBHOOK_SECRET. */
+    /**
+     * The project's Files (docs: files), in this key's environment: uploads
+     * (avatars, product images, downloads) with a permanent link to put in a
+     * page or a post. AI images and speech made with this key land here too.
+     */
+    readonly files: {
+        /** Upload bytes or a Blob (at most 50 MB) → the file, with its `url`. */
+        upload: (file: Uint8Array | Blob, opts: {
+            name: string;
+            contentType?: string;
+            folder?: string;
+            private?: boolean;
+        }) => Promise<AppFile>;
+        /** Newest first; `q` matches the name, the AI prompt, tags and note. */
+        list: (opts?: {
+            type?: AppFile["kind"];
+            source?: AppFile["source"];
+            q?: string;
+            folder?: string;
+            /** An ISO time or date, or relative: `30m`, `4h`, `2d`, `1w`. */
+            since?: string;
+            until?: string;
+            model?: string;
+            tag?: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<{
+            data: AppFile[];
+            has_more: boolean;
+            next_cursor: string | null;
+            total_files: number;
+            total_bytes: number;
+        }>;
+        /** The newest file matching the filters (`not_found` when none). */
+        latest: (opts?: {
+            type?: AppFile["kind"];
+            source?: AppFile["source"];
+            model?: string;
+            tag?: string;
+        }) => Promise<AppFile>;
+        get: (id: string) => Promise<AppFile>;
+        /** Delete it: its link stops working. */
+        delete: (id: string) => Promise<{
+            object: "file";
+            id: string;
+            deleted: true;
+        }>;
+    };
+    /**
+     * The project's contacts (docs: email ▸ Contacts): who gets its newsletters and
+     * automations. Add users at signup, keep their properties current, and track
+     * what they do to start automations (`track(email, 'upgraded')`). Nobody who
+     * unsubscribed, bounced or complained is subscribed again by an upsert. A
+     * development key answers but stores nothing.
+     */
+    readonly contacts: {
+        upsert: (input: ContactInput) => Promise<Contact>;
+        /** Something the contact did: segments and automations (event triggers, exit events) read it. */
+        track: (email: string, event: string, properties?: Record<string, string | number | boolean | null>) => Promise<{
+            object: "contact_event";
+            recorded: boolean;
+            reason?: string;
+        }>;
+        /** They asked to stop (your own settings page): no more marketing email from this project. */
+        unsubscribe: (email: string) => Promise<{
+            object: "contact";
+            email: string;
+            found: boolean;
+        }>;
+        get: (email: string) => Promise<Contact>;
+        /** Forget them (an account deleted). An address that left stays suppressed. */
+        delete: (email: string) => Promise<{
+            object: "contact";
+            deleted: boolean;
+        }>;
+    };
+    /**
+     * Webhooks from Vibiz. `receive(request)` is all a route needs with only
+     * VIBIZ_APP_KEY on the host: it reads the raw body and the signature, and
+     * fetches the signing secret with the app key when the env doesn't hold it
+     * (again once if a signature doesn't match, in case it was rotated).
+     * `verify(rawBody, header)` is the synchronous check with VIBIZ_WEBHOOK_SECRET.
+     */
     readonly webhooks: {
         verify: <T = unknown>(rawBody: string, header: string | null | undefined, secret?: string) => WebhookEvent<T>;
+        receive: <T = unknown>(request: {
+            text(): Promise<string>;
+            headers: {
+                get(name: string): string | null;
+            };
+        }) => Promise<WebhookEvent<T>>;
     };
     /**
      * A server-side event in the project's analytics, next to the browser's.

package/dist/index.js

@@ -145,7 +145,11 @@ function sameString(a, b) {
 function verifyWebhook(rawBody, header, secret = runtimeEnv().VIBIZ_WEBHOOK_SECRET, nowSeconds = Math.floor(Date.now() / 1e3)) {
   const bad = (why) => new VibizAppError(400, "invalid_signature", `Webhook refused: ${why}.`);
   if (!secret) {
-    throw new VibizAppError(500, "not_configured", "No VIBIZ_WEBHOOK_SECRET in the env.");
+    throw new VibizAppError(
+      500,
+      "not_configured",
+      "No VIBIZ_WEBHOOK_SECRET in the env. With only VIBIZ_APP_KEY, use `await vibiz.webhooks.receive(request)`."
+    );
   }
   if (!header) throw bad("no Vibiz-Signature header");
   let t;
@@ -173,9 +177,19 @@ function userHeader(user) {
   for (const b of new TextEncoder().encode(user)) bin += String.fromCharCode(b);
   return `b64u:${btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")}`;
 }
+var query = (q) => {
+  const p = new URLSearchParams();
+  for (const [k, v] of Object.entries(q)) if (v !== void 0 && v !== "") p.set(k, String(v));
+  const s = p.toString();
+  return s ? `?${s}` : "";
+};
 var VibizApp = class _VibizApp {
   options;
   loaded = null;
+  /** When `webhooks.receive` last fetched the signing secret again. */
+  secretRefreshedAt = 0;
+  /** The signing secret as Vibiz last gave it to `webhooks.receive`. */
+  webhookSecret;
   constructor(options = {}) {
     this.options = options;
   }
@@ -207,14 +221,16 @@ var VibizApp = class _VibizApp {
       );
     }
     const res = await (this.options.fetch ?? fetch)(`${this.url}/v1${path}`, {
-      method: init.method ?? (init.body === void 0 ? "GET" : "POST"),
+      method: init.method ?? (init.body === void 0 && !init.raw ? "GET" : "POST"),
       headers: {
         authorization: `Bearer ${this.key}`,
         accept: "application/json",
         ...init.body !== void 0 ? { "content-type": "application/json" } : {},
+        ...init.raw ? { "content-type": init.contentType ?? "application/octet-stream" } : {},
         ...this.options.user ? { "x-vibiz-user": userHeader(this.options.user) } : {}
       },
-      ...init.body !== void 0 ? { body: JSON.stringify(init.body) } : {}
+      ...init.body !== void 0 ? { body: JSON.stringify(init.body) } : {},
+      ...init.raw ? { body: init.raw } : {}
     });
     const text = await res.text();
     let data = null;
@@ -285,7 +301,11 @@ var VibizApp = class _VibizApp {
   email = {
     send: (input) => this.actions.run("email.send", input)
   };
-  /** Any action (`web.scrape`, `web.search`, `places.search`, `email.send`…), billed to the project. */
+  /**
+   * Any action, billed to the project: web data (`web.scrape`, `web.search`, `web.crawl`,
+   * `web.screenshot`, `web.design`, `ads.library`, `places.search`, `reviews`, `social.profile`,
+   * `social.posts`, `ecommerce.product`, `linkedin.company`) or `email.send`.
+   */
   actions = {
     run: (name, input) => this.request(`/app/actions/${encodeURIComponent(name)}`, {
       body: { input }
@@ -355,9 +375,94 @@ var VibizApp = class _VibizApp {
       body: { operation, ...input }
     })
   };
-  /** Webhooks from Vibiz: `verify(rawBody, header)` checks the signature with VIBIZ_WEBHOOK_SECRET. */
+  /**
+   * The project's Files (docs: files), in this key's environment: uploads
+   * (avatars, product images, downloads) with a permanent link to put in a
+   * page or a post. AI images and speech made with this key land here too.
+   */
+  files = {
+    /** Upload bytes or a Blob (at most 50 MB) → the file, with its `url`. */
+    upload: async (file, opts) => {
+      const raw = file instanceof Uint8Array ? file : new Uint8Array(await file.arrayBuffer());
+      const contentType = opts.contentType ?? (file instanceof Blob && file.type ? file.type : void 0);
+      return this.request(
+        `/app/files${query({ name: opts.name, folder: opts.folder, private: opts.private ? 1 : void 0 })}`,
+        { raw, ...contentType ? { contentType } : {} }
+      );
+    },
+    /** Newest first; `q` matches the name, the AI prompt, tags and note. */
+    list: (opts = {}) => this.request(`/app/files${query(opts)}`),
+    /** The newest file matching the filters (`not_found` when none). */
+    latest: (opts = {}) => this.request(`/app/files/latest${query(opts)}`),
+    get: (id) => this.request(`/app/files/${encodeURIComponent(id)}`),
+    /** Delete it: its link stops working. */
+    delete: (id) => this.request(
+      `/app/files/${encodeURIComponent(id)}`,
+      { method: "DELETE" }
+    )
+  };
+  /**
+   * The project's contacts (docs: email ▸ Contacts): who gets its newsletters and
+   * automations. Add users at signup, keep their properties current, and track
+   * what they do to start automations (`track(email, 'upgraded')`). Nobody who
+   * unsubscribed, bounced or complained is subscribed again by an upsert. A
+   * development key answers but stores nothing.
+   */
+  contacts = {
+    upsert: (input) => this.request("/app/contacts", { body: input }),
+    /** Something the contact did: segments and automations (event triggers, exit events) read it. */
+    track: (email, event, properties) => this.request(
+      "/app/contacts/events",
+      {
+        body: { email, event, ...properties ? { properties } : {} }
+      }
+    ),
+    /** They asked to stop (your own settings page): no more marketing email from this project. */
+    unsubscribe: (email) => this.request(
+      "/app/contacts/unsubscribe",
+      {
+        body: { email }
+      }
+    ),
+    get: (email) => this.request(`/app/contacts/${encodeURIComponent(email)}`),
+    /** Forget them (an account deleted). An address that left stays suppressed. */
+    delete: (email) => this.request(
+      `/app/contacts/${encodeURIComponent(email)}`,
+      {
+        method: "DELETE"
+      }
+    )
+  };
+  /**
+   * Webhooks from Vibiz. `receive(request)` is all a route needs with only
+   * VIBIZ_APP_KEY on the host: it reads the raw body and the signature, and
+   * fetches the signing secret with the app key when the env doesn't hold it
+   * (again once if a signature doesn't match, in case it was rotated).
+   * `verify(rawBody, header)` is the synchronous check with VIBIZ_WEBHOOK_SECRET.
+   */
   webhooks = {
-    verify: (rawBody, header, secret) => verifyWebhook(rawBody, header, secret)
+    verify: (rawBody, header, secret) => verifyWebhook(rawBody, header, secret),
+    receive: async (request) => {
+      const raw = await request.text();
+      const header = request.headers.get("vibiz-signature");
+      const secret = async (refresh = false) => {
+        if (!refresh) {
+          const known = this.webhookSecret ?? runtimeEnv().VIBIZ_WEBHOOK_SECRET;
+          if (known) return known;
+        }
+        this.webhookSecret = (await this.loadEnv({ refresh })).VIBIZ_WEBHOOK_SECRET;
+        return this.webhookSecret;
+      };
+      try {
+        return verifyWebhook(raw, header, await secret());
+      } catch (e) {
+        const reason = e instanceof VibizAppError ? e.code : "";
+        if (reason !== "invalid_signature" && reason !== "not_configured") throw e;
+        if (Date.now() - this.secretRefreshedAt < 6e4) throw e;
+        this.secretRefreshedAt = Date.now();
+        return verifyWebhook(raw, header, await secret(true));
+      }
+    }
   };
   /**
    * A server-side event in the project's analytics, next to the browser's.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibiz/app",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "One key for your app: env, AI, email, actions and events from Vibiz Stack.",
   "keywords": [
     "vibiz",