@vibiz/app 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @vibiz/app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One key for your app on [Vibiz Stack](https://app.vibiz.app): its env, AI, email, actions and
+server-side events.
+
+```bash
+npm install @vibiz/app
+```
+
+```ts
+import { vibiz } from '@vibiz/app';
+
+await vibiz.loadEnv();                         // hosts that hold only VIBIZ_APP_KEY
+const openai = new OpenAI(vibiz.ai);           // OpenAI-compatible AI gateway
+await vibiz.email.send({ to, subject, text });
+await vibiz.user(userId).track('Upgraded', { properties: { plan: 'pro' } });
+```
+
+`VIBIZ_APP_KEY` is in your app's env already when it runs on Vibiz hosting or a connected host.
+It is a server secret: never ship it to a browser.
+
+No dependencies. Node 20+, Bun, Deno and edge runtimes; ESM with TypeScript types.
+Docs: https://app.vibiz.app/docs/app-sdk

package/dist/index.d.ts

@@ -0,0 +1,505 @@
+/**
+ * @vibiz/app: everything a running app needs from Vibiz Stack, on one key.
+ *
+ *   import { vibiz } from '@vibiz/app';
+ *   await vibiz.loadEnv();                       // hosts that hold only VIBIZ_APP_KEY
+ *   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
+ * browser. No dependencies; Node 18+, Bun, Deno and edge runtimes.
+ */
+export interface VibizAppOptions {
+    /** Default: `VIBIZ_APP_KEY`. */
+    key?: string;
+    /** Default: `VIBIZ_API_URL`, then https://app.vibiz.app. */
+    url?: string;
+    /**
+     * Your own user's id (a stable pseudonymous id, not an email), for spend and
+     * events per user. `vibiz.user(id)` sets it per request.
+     */
+    user?: string;
+    fetch?: typeof fetch;
+    /** The key is a server secret. Set only if you understand who can read it. */
+    dangerouslyAllowBrowser?: boolean;
+}
+/** An error from Vibiz: the public `code` (`rate_limited`, `invalid_request`…) and HTTP status. */
+export declare class VibizAppError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: unknown;
+    constructor(status: number, code: string, message: string, details?: unknown);
+}
+export interface SendEmail {
+    to: string;
+    subject: string;
+    text?: string;
+    html?: string;
+    /** The mailbox on the project's mail domain: `info` → `info@<project>.vibiz.app`. */
+    from?: string;
+    from_name?: string;
+    reply_to?: string;
+}
+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';
+    content: string;
+}
+export interface TrackOptions {
+    /** Defaults to the client's user. */
+    user?: string;
+    path?: string;
+    properties?: Record<string, string | number | boolean | null>;
+}
+/** A payment, as the API returns it (docs/PAYMENTS.md). */
+export interface Payment {
+    object: 'payment';
+    id: string;
+    status: 'succeeded' | 'refunded' | 'partially_refunded' | 'disputed' | 'failed';
+    amount_cents: number;
+    refunded_cents: number;
+    fee_cents: number;
+    net_cents: number;
+    currency: 'usd';
+    description: string | null;
+    user: string | null;
+    customer_email: string | null;
+    price_id: string | null;
+    subscription_id: string | null;
+    metadata: Record<string, string>;
+    card: {
+        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;
+        reason: string;
+    } | null;
+    available_at: string;
+    created_at: string;
+}
+export interface Subscription {
+    object: 'subscription';
+    id: string;
+    status: 'active' | 'trialing' | 'past_due' | 'canceled' | 'incomplete' | 'unpaid';
+    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;
+}
+export interface Price {
+    object: 'price';
+    id: string;
+    product_id: string;
+    active: boolean;
+    unit_amount_cents: number;
+    currency: 'usd';
+    type: 'one_time' | 'recurring';
+    interval: 'day' | 'week' | 'month' | 'year' | null;
+    interval_count: number | null;
+    lookup_key: string | null;
+}
+export interface Product {
+    object: 'product';
+    id: string;
+    name: string;
+    description: string | null;
+    active: boolean;
+    prices: Price[];
+    created_at: string;
+}
+export interface CheckoutInput {
+    /** One of these… */
+    price_id?: string;
+    lookup_key?: string;
+    /** …or an ad-hoc one-time item. */
+    amount_cents?: number;
+    name?: string;
+    quantity?: number;
+    /** Your own user's id: their payments and subscriptions are found by it. */
+    user?: string;
+    customer_email?: string;
+    success_url: string;
+    cancel_url: string;
+    /** Up to 20 keys, echoed on the payment and in webhooks. */
+    metadata?: Record<string, string>;
+}
+/** An event Vibiz sent to your webhook, verified. */
+/** A connector as the app sees it: what it may call, never a key. */
+export interface AppConnector {
+    object: 'connector';
+    name: string;
+    label: string;
+    ready: boolean;
+    pricing: {
+        billed_by: string;
+        url: string | null;
+    };
+    operations: Array<{
+        id: string;
+        method: string;
+        path: string;
+        description: string;
+        risk: 'read' | 'write' | 'dangerous';
+        params: Record<string, unknown>;
+        body: Record<string, unknown> | null;
+    }>;
+}
+/** An API's answer through a connector: its status (a 404 there is `ok: false`), headers and data. */
+export interface ConnectorResponse<T = unknown> {
+    object: 'connector_response';
+    call_id: string;
+    connector: string;
+    operation: string;
+    environment: 'production' | 'development';
+    status: number;
+    ok: boolean;
+    headers: Record<string, string>;
+    content_type: string | null;
+    data: T;
+    data_base64?: string;
+    truncated: boolean;
+    untrusted: true;
+    notice: string;
+    pricing: {
+        billed_by: string;
+        url: string | null;
+    };
+    duration_ms: number;
+}
+export interface WebhookEvent<T = unknown> {
+    id: string;
+    object: 'event';
+    type: string;
+    created: number;
+    environment: 'production' | 'development';
+    data: {
+        object: T;
+    };
+}
+/**
+ * Check a webhook from Vibiz: `Vibiz-Signature: t=<unix>,v1=<hex HMAC-SHA256 of
+ * "${t}.${body}">` with your `VIBIZ_WEBHOOK_SECRET`, at most 5 minutes old.
+ * 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();
+    private get url();
+    /** A client that attributes spend and events to one of your users. */
+    user(id: string): VibizApp;
+    private request;
+    /** Which project and environment this key is. */
+    whoami(): Promise<{
+        project_id: string;
+        environment: "production" | "development";
+    }>;
+    /**
+     * Fetch the app's env from Vibiz and put it into `process.env` (existing
+     * variables win unless `override`). For hosts that hold only VIBIZ_APP_KEY:
+     * call it once at boot, before anything reads the env. Fetched once per
+     * process; `refresh: true` fetches again (after a rotation).
+     */
+    loadEnv(opts?: {
+        override?: boolean;
+        refresh?: boolean;
+    }): Promise<Record<string, string>>;
+    /**
+     * The AI gateway, OpenAI-compatible: `new OpenAI(vibiz.ai)` or the Vercel AI
+     * SDK's `createOpenAI(vibiz.ai)`. Models: `vibiz/fast`, `vibiz/smart`…
+     */
+    get ai(): {
+        readonly baseURL: string;
+        readonly apiKey: string;
+        /** One chat completion, without an SDK. */
+        chat: (input: {
+            messages: ChatMessage[];
+            model?: string;
+            max_tokens?: number;
+            temperature?: number;
+        }) => Promise<{
+            choices: {
+                message: {
+                    role: string;
+                    content: string | null;
+                };
+            }[];
+            usage?: {
+                prompt_tokens: number;
+                completion_tokens: number;
+            };
+            cost_micro_usd?: number;
+        }>;
+    };
+    /** Email from the project's own address (needs the `email` resource). */
+    readonly email: {
+        send: (input: SendEmail) => Promise<ActionResult<{
+            id: string;
+            from: string;
+            status: string;
+        }>>;
+    };
+    /**
+     * 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>>;
+    };
+    /**
+     * Payments (docs/PAYMENTS.md): Vibiz is the merchant, so this works from the
+     * first call, before the owner has verified anything. Refunds and
+     * withdrawals are the owner's, in the console.
+     */
+    readonly payments: {
+        /** A hosted checkout page for a price (one-time or a subscription) or an ad-hoc item. */
+        checkout: (input: CheckoutInput) => Promise<{
+            object: "checkout";
+            id: string;
+            url: string;
+            expires_at: string;
+        }>;
+        /** The user's live subscription (active, trialing or past due), or null. */
+        subscription: (user: string) => Promise<Subscription | null>;
+        /** Whether the user has an active (or trialing) subscription, optionally to one price id or lookup key. */
+        hasActive: (user: string, price?: string) => Promise<boolean>;
+        /** A link where the user manages their subscription and card. */
+        portal: (user: string, opts: {
+            return_url: string;
+        }) => Promise<{
+            object: "portal_session";
+            url: string;
+        }>;
+        /** The catalog: products with their prices. */
+        products: () => Promise<Product[]>;
+        /** Payments, newest first (`user` keeps one of yours). */
+        payments: (opts?: {
+            user?: string;
+            cursor?: string;
+            limit?: number;
+        }) => Promise<{
+            data: Payment[];
+            has_more: boolean;
+            next_cursor: string | null;
+        }>;
+        /** Cancel a user's subscription (at the end of the period by default). */
+        cancel: (subscriptionId: string, opts?: {
+            at_period_end?: boolean;
+        }) => Promise<Subscription>;
+    };
+    /**
+     * Your connectors (docs/CONNECTORS.md): call an API through Vibiz, which
+     * holds the key for this app's environment. The answer's `data` is the
+     * API's own content. A dangerous operation needs the owner's permission.
+     */
+    readonly connectors: {
+        /** The connectors with their enabled operations and parameters. */
+        list: () => Promise<AppConnector[]>;
+        call: <T = unknown>(name: string, operation: string, input?: {
+            params?: Record<string, unknown>;
+            body?: unknown;
+        }) => Promise<ConnectorResponse<T>>;
+    };
+    /**
+     * 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.
+     * Never throws: analytics must not break the request that tracks it.
+     * Returns whether it was recorded (development keys don't record).
+     */
+    track(name: string, opts?: TrackOptions): Promise<boolean>;
+}
+/** Create a client with explicit options. */
+export declare const createVibiz: (options?: VibizAppOptions) => VibizApp;
+/** The default client: VIBIZ_APP_KEY and VIBIZ_API_URL from the environment, read on use. */
+export declare const vibiz: VibizApp;

package/dist/index.js

@@ -0,0 +1,500 @@
+// packages/app/src/index.ts
+var runtimeEnv = () => globalThis.process?.env ?? {};
+var DEFAULT_URL = "https://app.vibiz.app";
+var VibizAppError = class extends Error {
+  status;
+  code;
+  details;
+  constructor(status, code, message, details) {
+    super(message);
+    this.name = "VibizAppError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+var WEBHOOK_TOLERANCE_S = 300;
+var K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+function sha256(data) {
+  const h = [
+    1779033703,
+    3144134277,
+    1013904242,
+    2773480762,
+    1359893119,
+    2600822924,
+    528734635,
+    1541459225
+  ];
+  const blocks = Math.ceil((data.length + 9) / 64);
+  const buf = new Uint8Array(blocks * 64);
+  buf.set(data);
+  buf[data.length] = 128;
+  const view = new DataView(buf.buffer);
+  view.setUint32(buf.length - 8, Math.floor(data.length / 536870912));
+  view.setUint32(buf.length - 4, data.length << 3 >>> 0);
+  const w = new Array(64).fill(0);
+  const rotr = (x, n) => x >>> n | x << 32 - n;
+  for (let b = 0; b < blocks; b++) {
+    for (let i = 0; i < 16; i++) w[i] = view.getUint32(b * 64 + i * 4);
+    for (let i = 16; i < 64; i++) {
+      const a15 = w[i - 15] ?? 0;
+      const a2 = w[i - 2] ?? 0;
+      const s0 = rotr(a15, 7) ^ rotr(a15, 18) ^ a15 >>> 3;
+      const s1 = rotr(a2, 17) ^ rotr(a2, 19) ^ a2 >>> 10;
+      w[i] = (w[i - 16] ?? 0) + s0 + (w[i - 7] ?? 0) + s1 >>> 0;
+    }
+    const v = [...h];
+    for (let i = 0; i < 64; i++) {
+      const [a = 0, bb = 0, c = 0, d = 0, e = 0, f = 0, g = 0, hh = 0] = v;
+      const t1 = hh + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + (e & f ^ ~e & g) + (K[i] ?? 0) + (w[i] ?? 0) >>> 0;
+      const t2 = (rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + (a & bb ^ a & c ^ bb & c) >>> 0;
+      v.splice(0, 8, t1 + t2 >>> 0, a, bb, c, d + t1 >>> 0, e, f, g);
+    }
+    for (let i = 0; i < 8; i++) h[i] = (h[i] ?? 0) + (v[i] ?? 0) >>> 0;
+  }
+  const digest = new Uint8Array(32);
+  const dv = new DataView(digest.buffer);
+  for (let i = 0; i < 8; i++) dv.setUint32(i * 4, h[i] ?? 0);
+  return digest;
+}
+function hmacSha256Hex(key, message) {
+  const enc = new TextEncoder();
+  let k = enc.encode(key);
+  if (k.length > 64) k = sha256(k);
+  const pad = (byte, rest) => {
+    const out = new Uint8Array(64 + rest.length);
+    for (let i = 0; i < 64; i++) out[i] = (k[i] ?? 0) ^ byte;
+    out.set(rest, 64);
+    return out;
+  };
+  const inner = sha256(pad(54, enc.encode(message)));
+  return [...sha256(pad(92, inner))].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function sameString(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+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. With only VIBIZ_APP_KEY, use `await vibiz.webhooks.receive(request)`."
+    );
+  }
+  if (!header) throw bad("no Vibiz-Signature header");
+  let t;
+  const sigs = [];
+  for (const part of header.split(",")) {
+    const i = part.indexOf("=");
+    const k = part.slice(0, i).trim();
+    const v = part.slice(i + 1).trim();
+    if (k === "t" && /^\d{1,12}$/.test(v)) t = Number(v);
+    else if (k === "v1" && v) sigs.push(v.toLowerCase());
+  }
+  if (t === void 0 || !sigs.length) throw bad("malformed signature");
+  if (Math.abs(nowSeconds - t) > WEBHOOK_TOLERANCE_S) throw bad("too old");
+  const expected = hmacSha256Hex(secret, `${t}.${rawBody}`);
+  if (!sigs.some((sig) => sameString(sig, expected))) throw bad("signature does not match");
+  try {
+    return JSON.parse(rawBody);
+  } catch {
+    throw bad("not JSON");
+  }
+}
+function userHeader(user) {
+  if (/^[\x20-\x7e]*$/.test(user) && !user.startsWith("b64u:")) return user;
+  let bin = "";
+  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;
+  }
+  /** The key, read when first needed, so `loadEnv()` or a late env still works. */
+  get key() {
+    const key = this.options.key ?? runtimeEnv().VIBIZ_APP_KEY;
+    if (!key) {
+      throw new VibizAppError(
+        401,
+        "unauthorized",
+        "No app key. Set VIBIZ_APP_KEY (Vibiz puts it in your app\u2019s env), or pass { key }."
+      );
+    }
+    return key;
+  }
+  get url() {
+    return (this.options.url ?? runtimeEnv().VIBIZ_API_URL ?? DEFAULT_URL).replace(/\/$/, "");
+  }
+  /** A client that attributes spend and events to one of your users. */
+  user(id) {
+    return new _VibizApp({ ...this.options, user: id });
+  }
+  async request(path, init = {}) {
+    if (typeof globalThis.window !== "undefined" && !this.options.dangerouslyAllowBrowser) {
+      throw new VibizAppError(
+        400,
+        "invalid_request",
+        "The app key is a server secret: call Vibiz from your server, not the browser."
+      );
+    }
+    const res = await (this.options.fetch ?? fetch)(`${this.url}/v1${path}`, {
+      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.raw ? { body: init.raw } : {}
+    });
+    const text = await res.text();
+    let data = null;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {
+      data = null;
+    }
+    if (!res.ok) {
+      const e = data?.error;
+      throw new VibizAppError(
+        res.status,
+        e?.code ?? "error",
+        e?.message ?? `Vibiz answered ${res.status}.`,
+        e?.details
+      );
+    }
+    return data;
+  }
+  /** Which project and environment this key is. */
+  whoami() {
+    return this.request("/app");
+  }
+  /**
+   * Fetch the app's env from Vibiz and put it into `process.env` (existing
+   * variables win unless `override`). For hosts that hold only VIBIZ_APP_KEY:
+   * call it once at boot, before anything reads the env. Fetched once per
+   * process; `refresh: true` fetches again (after a rotation).
+   */
+  async loadEnv(opts = {}) {
+    if (!this.loaded || opts.refresh) {
+      this.loaded = this.request("/app/env").then((r) => r.env);
+      this.loaded.catch(() => {
+        this.loaded = null;
+      });
+    }
+    const env = await this.loaded;
+    const target = runtimeEnv();
+    for (const [k, v] of Object.entries(env)) {
+      if (opts.override || target[k] === void 0) target[k] = v;
+    }
+    return env;
+  }
+  /**
+   * The AI gateway, OpenAI-compatible: `new OpenAI(vibiz.ai)` or the Vercel AI
+   * SDK's `createOpenAI(vibiz.ai)`. Models: `vibiz/fast`, `vibiz/smart`…
+   */
+  get ai() {
+    const self = this;
+    return {
+      get baseURL() {
+        return `${self.url}/v1/ai`;
+      },
+      get apiKey() {
+        return self.key;
+      },
+      /** One chat completion, without an SDK. */
+      chat: (input) => self.request("/ai/chat/completions", {
+        body: {
+          model: "vibiz/fast",
+          ...input,
+          ...self.options.user ? { user: self.options.user } : {}
+        }
+      })
+    };
+  }
+  /** Email from the project's own address (needs the `email` resource). */
+  email = {
+    send: (input) => this.actions.run("email.send", input)
+  };
+  /**
+   * 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 }
+    })
+  };
+  /**
+   * Payments (docs/PAYMENTS.md): Vibiz is the merchant, so this works from the
+   * first call, before the owner has verified anything. Refunds and
+   * withdrawals are the owner's, in the console.
+   */
+  payments = {
+    /** A hosted checkout page for a price (one-time or a subscription) or an ad-hoc item. */
+    checkout: (input) => this.request(
+      "/app/payments/checkout",
+      { body: input }
+    ),
+    /** The user's live subscription (active, trialing or past due), or null. */
+    subscription: async (user) => {
+      const r = await this.request(
+        `/app/payments/subscriptions?user=${encodeURIComponent(user)}&status=active,trialing,past_due`
+      );
+      return r.data[0] ?? null;
+    },
+    /** Whether the user has an active (or trialing) subscription, optionally to one price id or lookup key. */
+    hasActive: async (user, price) => {
+      const r = await this.request(
+        `/app/payments/subscriptions?user=${encodeURIComponent(user)}&status=active,trialing`
+      );
+      if (!price) return r.data.length > 0;
+      if (r.data.some((x) => x.price_id === price)) return true;
+      const products = await this.payments.products();
+      const ids = new Set(
+        products.flatMap((p) => p.prices).filter((p) => p.lookup_key === price).map((p) => p.id)
+      );
+      return r.data.some((x) => x.price_id !== null && ids.has(x.price_id));
+    },
+    /** A link where the user manages their subscription and card. */
+    portal: (user, opts) => this.request("/app/payments/portal", {
+      body: { user, return_url: opts.return_url }
+    }),
+    /** The catalog: products with their prices. */
+    products: () => this.request("/app/payments/products").then((r) => r.data),
+    /** Payments, newest first (`user` keeps one of yours). */
+    payments: (opts = {}) => {
+      const q = new URLSearchParams();
+      for (const [k, v] of Object.entries(opts)) if (v !== void 0) q.set(k, String(v));
+      const qs = q.toString();
+      return this.request(
+        `/app/payments/payments${qs ? `?${qs}` : ""}`
+      );
+    },
+    /** Cancel a user's subscription (at the end of the period by default). */
+    cancel: (subscriptionId, opts = {}) => this.request(
+      `/app/payments/subscriptions/${encodeURIComponent(subscriptionId)}/cancel`,
+      { body: opts }
+    )
+  };
+  /**
+   * Your connectors (docs/CONNECTORS.md): call an API through Vibiz, which
+   * holds the key for this app's environment. The answer's `data` is the
+   * API's own content. A dangerous operation needs the owner's permission.
+   */
+  connectors = {
+    /** The connectors with their enabled operations and parameters. */
+    list: () => this.request("/app/connectors").then((r) => r.data),
+    call: (name, operation, input = {}) => this.request(`/app/connectors/${encodeURIComponent(name)}/call`, {
+      body: { operation, ...input }
+    })
+  };
+  /**
+   * 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),
+    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.
+   * Never throws: analytics must not break the request that tracks it.
+   * Returns whether it was recorded (development keys don't record).
+   */
+  async track(name, opts = {}) {
+    try {
+      const user = opts.user ?? this.options.user;
+      const r = await this.request("/app/events", {
+        body: {
+          name,
+          ...user ? { user } : {},
+          ...opts.path ? { path: opts.path } : {},
+          ...opts.properties ? { properties: opts.properties } : {}
+        }
+      });
+      return r.recorded;
+    } catch (e) {
+      globalThis.console?.warn?.(
+        `vibiz.track(${name}) failed: ${e instanceof Error ? e.message : String(e)}`
+      );
+      return false;
+    }
+  }
+};
+var createVibiz = (options) => new VibizApp(options);
+var vibiz = new VibizApp();
+export {
+  VibizApp,
+  VibizAppError,
+  createVibiz,
+  verifyWebhook,
+  vibiz
+};

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@vibiz/app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "One key for your app: env, AI, email, actions and events from Vibiz Stack.",
+  "keywords": [
+    "vibiz",
+    "env",
+    "ai",
+    "email",
+    "analytics"
+  ],
+  "homepage": "https://app.vibiz.app/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vibiz-ai/vibiz-stack.git",
+    "directory": "packages/app"
+  },
+  "bugs": {
+    "url": "https://github.com/Vibiz-ai/vibiz-stack/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts"
+}