@mirafive/protocol 0.0.0-stage → 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cloo GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# @mirafive/protocol
 
-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.
+The MIRA FIVE wire format and the helpers every MIRA FIVE SDK shares: event and batch types,
+limits, reserved names, `eventIdFor`, UUIDv7, property cleaning and retry rules. No
+dependencies; runs in browsers, Node, Bun, Deno, workers and Convex.
+
+The MIRA FIVE ingest checks its own schema against this package on every build, so what
+`validateBatch` accepts is what the ingest accepts.
+
+You rarely install it yourself: [`@mirafive/web`](https://github.com/mirafive/sdk-web) and
+[`@mirafive/node`](https://github.com/mirafive/sdk-node) depend on it. Use it to build your own
+integration, to validate batches, or to port MIRA FIVE to another language.
+
+## Contents
+
+| Export                                                                                                                     | What it is                                                                                                                                        |
+| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WireEvent`, `WireBatch`, `BatchResult`, `EventContext`, `Revenue`, `Consent`                                              | The types of what `POST /v1/batch` accepts and answers. They are checked against the ingest's own schema on every build, so they cannot drift.    |
+| `LIMITS`, `reservedEvents`, `externalIdTypes`, `revenueKinds`, `billingIntervals`, `touchpointKinds`, `touchpointChannels` | The rules, as values.                                                                                                                             |
+| `eventIdFor(key)`                                                                                                          | A stable event id from your own key: UUIDv8 from SHA-256. The same key gives the same id in every MIRA FIVE SDK and language.                     |
+| `uuidv7()`                                                                                                                 | Time-ordered event ids.                                                                                                                           |
+| `cleanProperties(value)`, `cleanExternalIds(value)`                                                                        | Make arbitrary values fit the wire: flatten objects to dot keys, apply the limits.                                                                |
+| `retryable(status)`, `backoffMs(attempt, atLeastMs)`, `retryAfterMs(header)`                                               | The retry rules every SDK follows.                                                                                                                |
+| `keyKind(key)`                                                                                                             | `"public"` (`mira_pk_…`), `"secret"` (`mira_sk_…`) or `"unknown"`.                                                                                |
+| `validateBatch(batch)`, `validateEvent(event)`                                                                             | Every problem the ingest would reject, as `{ path, message }`; an empty list means accepted. No dependencies.                                     |
+| `mirafive-validate` (`npx @mirafive/protocol batches.json`)                                                                | The same check on the command line, for SDKs in other languages and CI: one batch or a list, from a file or standard input; exits 1 on a problem. |
+| `@mirafive/protocol/batch.schema.json`                                                                                     | JSON Schema (2020-12) of a batch, generated from the ingest's schema.                                                                             |
+| `@mirafive/protocol/fixtures/event-ids.json`                                                                               | `eventIdFor` test vectors for SDKs in other languages.                                                                                            |
+| `@mirafive/protocol/fixtures/batches/{valid,invalid}/*.json`                                                               | Batches the ingest accepts and rejects, for SDK test suites.                                                                                      |
+
+## The wire in one request
+
+```sh
+curl https://events.mirafive.io/v1/batch \
+  -H "Authorization: Bearer $MIRAFIVE_SECRET_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"events":[{"event_id":"0192d4a8-7b1c-7e8a-9c1d-2b3e4f5a6b7c","type":"track","event":"report_exported","user_id":"user_42","consent":"not_applicable"}]}'
+```
+
+The answer is `{ "accepted": 1, "duplicates": 0, "rejected": [] }`. Events are checked one by
+one, so a bad event never sinks the batch; resend a batch with the same `event_id`s and it counts
+once.
+
+## For AI coding assistants
+
+Rules for integrating MIRA FIVE correctly. They hold for every MIRA FIVE SDK.
+
+- **Keys:** the public key (`mira_pk_…`) goes in browser and app code. The secret key (`mira_sk_…`)
+  goes only into the server's environment (`MIRAFIVE_SECRET_KEY`), never into client code, a
+  `NEXT_PUBLIC_`/`VITE_`/`PUBLIC_` variable or a repository. The SDKs refuse the wrong key.
+- **Money** is sent only from the server: integer minor units plus an ISO 4217 currency
+  (`amount: 1999, currency: "EUR"` is 19.99 EUR), never floats.
+- **Count once:** give money an `entryId` from the payment provider (`stripe:in_123`), so the
+  Stripe connector and retries do not double it. Give business events a stable id:
+  `eventId: await eventIdFor("order:123:paid")`. The same key gives the same id in every SDK.
+- **Personal data** never goes into event names or properties. Use your own user id (not an email)
+  for `identify`; put email, name and phone in its traits, which MIRA FIVE encrypts at rest.
+- **Consent:** keep `consent: "auto"`; it follows the site's consent banner (Usercentrics,
+  Cookiebot, consentmanager, CCM19, Borlabs, any TCF 2.2 CMP, Google Consent Mode). Call
+  `consent()` only for a custom banner. Do not gate the SDK behind consent yourself: without
+  consent it is cookieless and still counts.
+- **Never block on analytics:** event methods return nothing, never throw, and batch on their
+  own. Do not `await` or `try` them. Call `flush()`/`shutdown()` only at the end of a script or a
+  serverless function.
+- **Server events and visitors:** pass the browser's `mira.anonymousId` to your server and set it
+  as `anonymousId` on server events, so a purchase joins the visit and its source.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync } from "node:fs";
+
+// src/wire.ts
+var LIMITS = {
+  eventsPerBatch: 100,
+  nameLength: 120,
+  propertyKeys: 64,
+  propertyKeyLength: 100,
+  stringLength: 2048,
+  arrayLength: 50,
+  urlLength: 4096,
+  idLength: 200,
+  maxClientAgeDays: 7
+};
+var consentStates = ["granted", "denied", "unknown"];
+var externalIdTypes = [
+  "stripe_customer",
+  "revenuecat_app_user",
+  "shopify_customer",
+  "shopware_customer"
+];
+var revenueKinds = [
+  "charge",
+  "subscription_payment",
+  "refund",
+  "dispute",
+  "dispute_won"
+];
+var billingIntervals = ["day", "week", "month", "year"];
+var touchpointKinds = ["survey", "offline", "code", "custom"];
+var touchpointChannels = [
+  "paid_search",
+  "paid_social",
+  "paid_other",
+  "organic_search",
+  "organic_social",
+  "ai_assistant",
+  "email",
+  "affiliate",
+  "display",
+  "video",
+  "qr",
+  "app_store",
+  "referral",
+  "direct"
+];
+
+// src/validate.ts
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var join = (path, key) => path ? `${path}.${key}` : String(key);
+var UUID = /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/;
+var DATETIME = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|([+-])(\d{2}):(\d{2}))$/;
+function isDateTime(value) {
+  const match = DATETIME.exec(value);
+  if (!match)
+    return false;
+  const [, year, month, day, hour, minute, second, , offsetHour, offsetMinute] = match;
+  const days = new Date(Date.UTC(Number(year), Number(month), 0)).getUTCDate();
+  return Number(month) >= 1 && Number(month) <= 12 && Number(day) >= 1 && Number(day) <= days && Number(hour) <= 23 && Number(minute) <= 59 && Number(second) <= 59 && (offsetHour === undefined || Number(offsetHour) <= 23 && Number(offsetMinute) <= 59);
+}
+var string = (options) => (value, path, issues) => {
+  if (typeof value !== "string") {
+    issues.push({ path, message: "expected a string" });
+    return;
+  }
+  const text = options.trim ? value.trim() : value;
+  if (options.min !== undefined && text.length < options.min) {
+    issues.push({ path, message: `at least ${options.min} character(s)` });
+  } else if (text.length > options.max) {
+    issues.push({ path, message: `at most ${options.max} characters` });
+  }
+  if (options.pattern && !options.pattern.test(text)) {
+    issues.push({ path, message: options.hint ?? "invalid format" });
+  }
+};
+var dateTime = (value, path, issues) => {
+  if (typeof value !== "string" || !isDateTime(value)) {
+    issues.push({ path, message: "expected an ISO 8601 date and time with Z or an offset" });
+  }
+};
+var oneOf = (values) => (value, path, issues) => {
+  if (typeof value !== "string" || !values.includes(value)) {
+    issues.push({ path, message: `expected one of ${values.join(", ")}` });
+  }
+};
+var integer = (min, max) => (value, path, issues) => {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    {
+      issues.push({ path, message: "expected an integer" });
+      return;
+    }
+  }
+  if (value < min || value > max)
+    issues.push({ path, message: `expected ${min} to ${max}` });
+};
+var number = (options) => (value, path, issues) => {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    {
+      issues.push({ path, message: "expected a number" });
+      return;
+    }
+  }
+  if (options.int && !Number.isInteger(value))
+    issues.push({ path, message: "expected an integer" });
+  if (options.positive && value <= 0)
+    issues.push({ path, message: "expected a positive number" });
+  if (options.min !== undefined && value < options.min) {
+    issues.push({ path, message: `at least ${options.min}` });
+  }
+  if (options.max !== undefined && value > options.max) {
+    issues.push({ path, message: `at most ${options.max}` });
+  }
+};
+var object = (fields, required = []) => (value, path, issues) => {
+  if (!isObject(value)) {
+    issues.push({ path, message: "expected an object" });
+    return;
+  }
+  for (const [key, check] of Object.entries(fields)) {
+    if (value[key] === undefined) {
+      if (required.includes(key))
+        issues.push({ path: join(path, key), message: "required" });
+      continue;
+    }
+    check(value[key], join(path, key), issues);
+  }
+};
+var scalar = (value) => typeof value === "boolean" || typeof value === "number" && Number.isFinite(value) || typeof value === "string" && value.length <= LIMITS.stringLength;
+var properties = (value, path, issues) => {
+  if (!isObject(value)) {
+    issues.push({ path, message: "expected an object" });
+    return;
+  }
+  const keys = Object.keys(value);
+  for (const key of keys) {
+    const at = join(path, key);
+    if (key.length < 1 || key.length > LIMITS.propertyKeyLength) {
+      issues.push({ path: at, message: `keys have 1 to ${LIMITS.propertyKeyLength} characters` });
+    }
+    const item = value[key];
+    if (item === null || scalar(item))
+      continue;
+    if (Array.isArray(item)) {
+      if (item.length > LIMITS.arrayLength) {
+        issues.push({ path: at, message: `at most ${LIMITS.arrayLength} items` });
+      }
+      item.forEach((entry, index) => {
+        if (!scalar(entry)) {
+          issues.push({ path: join(at, index), message: "expected a string, number or boolean" });
+        }
+      });
+      continue;
+    }
+    issues.push({
+      path: at,
+      message: typeof item === "string" ? `at most ${LIMITS.stringLength} characters` : "expected a string, number, boolean, null or a list of them (nested objects are flattened by the SDKs)"
+    });
+  }
+  if (keys.length > LIMITS.propertyKeys) {
+    issues.push({ path, message: `at most ${LIMITS.propertyKeys} properties per event` });
+  }
+};
+var built;
+function rules() {
+  if (built)
+    return built;
+  const short = string({ max: LIMITS.stringLength });
+  const url = string({ max: LIMITS.urlLength });
+  const size = integer(0, 20000);
+  const context = object({
+    page: object({ url, referrer: url, title: short }),
+    app: object({ name: short, version: short, build: short, namespace: short }),
+    device: object({
+      type: oneOf(["desktop", "mobile", "tablet", "tv", "other"]),
+      manufacturer: short,
+      model: short
+    }),
+    os: object({ name: short, version: short }),
+    screen: object({ width: size, height: size, density: number({ positive: true, max: 10 }) }),
+    viewport: object({ width: size, height: size }),
+    locale: string({ max: 35 }),
+    languages: (value, path, issues) => {
+      if (!Array.isArray(value)) {
+        issues.push({ path, message: "expected a list" });
+        return;
+      }
+      if (value.length > 10)
+        issues.push({ path, message: "at most 10 languages" });
+      value.forEach((entry, index) => string({ max: 35 })(entry, join(path, index), issues));
+    },
+    timezone: string({ max: 64 }),
+    location: object({
+      latitude: number({ min: -90, max: 90 }),
+      longitude: number({ min: -180, max: 180 })
+    }, ["latitude", "longitude"]),
+    library: object({ name: string({ max: 50 }), version: string({ max: 30 }) }, [
+      "name",
+      "version"
+    ]),
+    ip: string({ max: 45 }),
+    user_agent: string({ max: 1024 })
+  });
+  const consentState = oneOf(consentStates);
+  const consent = (value, path, issues) => {
+    if (value === "not_applicable")
+      return;
+    if (!isObject(value)) {
+      {
+        issues.push({ path, message: 'expected { analytics, marketing } or "not_applicable"' });
+        return;
+      }
+    }
+    object({ analytics: consentState, marketing: consentState }, ["analytics"])(value, path, issues);
+  };
+  const minor = integer(-1000000000000000, 1000000000000000);
+  const id = string({ max: LIMITS.idLength });
+  const revenue = object({
+    amount: minor,
+    currency: string({ min: 3, max: 3, hint: "an ISO 4217 code" }),
+    entry_id: id,
+    kind: oneOf(revenueKinds),
+    fee: minor,
+    tax: minor,
+    refund_of: id,
+    product: id,
+    subscription: object({
+      id: string({ min: 1, max: LIMITS.idLength }),
+      interval: oneOf(billingIntervals),
+      interval_count: integer(1, 36),
+      period_start: dateTime,
+      period_end: dateTime
+    }, ["id"])
+  }, ["amount", "currency"]);
+  const externalIds = (value, path, issues) => {
+    if (!isObject(value)) {
+      issues.push({ path, message: "expected an object" });
+      return;
+    }
+    for (const [key, item] of Object.entries(value)) {
+      if (!externalIdTypes.includes(key)) {
+        issues.push({
+          path: join(path, key),
+          message: `expected one of ${externalIdTypes.join(", ")}`
+        });
+      } else if (item !== undefined) {
+        string({ min: 1, max: LIMITS.idLength })(item, join(path, key), issues);
+      }
+    }
+  };
+  const text = string({ max: 200, trim: true });
+  const touchpoint = object({
+    kind: oneOf(touchpointKinds),
+    channel: oneOf(touchpointChannels),
+    source: text,
+    medium: text,
+    campaign: text,
+    content: text,
+    campaign_id: text,
+    ad_group_id: text,
+    ad_id: text,
+    code: text,
+    answer: string({ max: 500, trim: true }),
+    external_ref: text
+  }, ["kind"]);
+  const event = object({
+    event_id: string({ max: 36, pattern: UUID, hint: "expected a UUID" }),
+    type: oneOf(["track", "page", "screen", "identify", "group"]),
+    event: string({
+      min: 1,
+      max: LIMITS.nameLength,
+      pattern: /^\P{Cc}+$/u,
+      hint: "no control characters"
+    }),
+    timestamp: dateTime,
+    anonymous_id: id,
+    user_id: id,
+    session_id: id,
+    group_id: id,
+    properties,
+    traits: properties,
+    external_ids: externalIds,
+    revenue,
+    context,
+    consent
+  }, ["event_id", "type", "event"]);
+  built = { event, touchpoint };
+  return built;
+}
+function validateEvent(value, path = "") {
+  const issues = [];
+  const { event, touchpoint } = rules();
+  event(value, path, issues);
+  if (isObject(value) && value.event === "$touchpoint") {
+    if (value.type !== "track") {
+      issues.push({ path: join(path, "type"), message: "$touchpoint is a track event" });
+    }
+    const props = isObject(value.properties) ? value.properties : {};
+    const before = issues.length;
+    touchpoint(props, join(path, "properties"), issues);
+    const source = typeof props.source === "string" ? props.source.trim() : "";
+    if (issues.length === before && !props.channel && !source) {
+      issues.push({
+        path: join(path, "properties.source"),
+        message: "a touchpoint needs a channel or a source"
+      });
+    }
+  }
+  return issues;
+}
+function validateBatch(value) {
+  const issues = [];
+  object({
+    key: string({ max: 100 }),
+    sent_at: dateTime,
+    stream: string({ min: 1, max: 64 }),
+    seq: integer(1, 2147483647)
+  })(value, "", issues);
+  if (!isObject(value))
+    return issues;
+  const events = value.events;
+  if (!Array.isArray(events)) {
+    issues.push({ path: "events", message: "expected a list of events" });
+    return issues;
+  }
+  if (events.length < 1 || events.length > LIMITS.eventsPerBatch) {
+    issues.push({ path: "events", message: `1 to ${LIMITS.eventsPerBatch} events per batch` });
+  }
+  events.forEach((item, index) => issues.push(...validateEvent(item, join("events", index))));
+  return issues;
+}
+
+// src/cli.ts
+var file = process.argv[2];
+var text = readFileSync(file && file !== "-" ? file : 0, "utf8");
+var input;
+try {
+  input = JSON.parse(text);
+} catch (error) {
+  console.error(`✗ not JSON: ${String(error)}`);
+  process.exit(1);
+}
+var batches = Array.isArray(input) ? input : [input];
+var failed = 0;
+var events = 0;
+batches.forEach((batch, index) => {
+  const issues = validateBatch(batch);
+  const list = typeof batch === "object" && batch !== null ? Reflect.get(batch, "events") : undefined;
+  if (Array.isArray(list))
+    events += list.length;
+  for (const issue of issues) {
+    failed += 1;
+    console.error(`✗ batch ${index}: ${issue.path || "(batch)"}: ${issue.message}`);
+  }
+});
+if (failed)
+  process.exit(1);
+console.log(`✓ ${batches.length} batch(es), ${events} event(s): valid`);

package/dist/helpers.d.ts

@@ -0,0 +1,35 @@
+import type { Consent, ConsentState } from "./wire.js";
+/** What callers may pass for one purpose: a plain boolean from a custom banner, or a wire state. */
+export type ConsentInput = boolean | ConsentState | undefined;
+/** `true` → granted, `false` → denied, nothing → unknown. */
+export declare const consentState: (value: ConsentInput) => ConsentState;
+/** Consent for an event from booleans or states; `not_applicable` passes through. */
+export declare function toConsent(input: "not_applicable" | {
+    analytics: ConsentInput;
+    marketing?: ConsentInput;
+} | undefined, fallback?: Consent): Consent;
+/**
+ * Which kind of key this is. Public keys (`mira_pk_…`) belong in browsers and apps; secret keys
+ * (`mira_sk_…`) only on servers, because they may send revenue and backfills.
+ */
+export declare function keyKind(key: string | undefined): "public" | "secret" | "unknown";
+/** Strips trailing slashes, so `host + "/v1/batch"` is always one URL. */
+export declare const trimHost: (host: string) => string;
+/** Answers worth retrying: timeouts, rate limits and server errors. Other 4xx are final. */
+export declare const retryable: (status: number) => boolean;
+/**
+ * Exponential backoff with full jitter, capped, but never sooner than the server asked
+ * (`Retry-After`, in milliseconds).
+ */
+export declare function backoffMs(attempt: number, atLeastMs?: number, baseMs?: number, capMs?: number): number;
+/** `Retry-After` in milliseconds: seconds or an HTTP date. 0 when absent or unreadable. */
+export declare function retryAfterMs(header: string | null, now?: number): number;
+/** A UUID of version 1 to 8 in the RFC 9562 variant, as the ingest accepts for `event_id`. */
+export declare const isUuid: (value: string) => boolean;
+/**
+ * A stable event id from your own key, such as `order:123:paid`. The same key always gives the
+ * same UUID, in every MIRA FIVE SDK and language, so a retried job, a backfill run twice, or the
+ * browser and the server reporting one conversion all count once.
+ * Format: UUIDv8 (RFC 9562) from the first 122 bits of SHA-256.
+ */
+export declare function eventIdFor(key: string): Promise<string>;

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@mirafive/protocol`: the MIRA FIVE wire format and the helpers every SDK shares. No
+ * dependencies; runs in browsers, Node, Bun, Deno, workers and Convex.
+ *
+ * Build your own integration on it, or read `batch.schema.json` (JSON Schema of a batch) from
+ * another language.
+ */
+export * from "./wire.js";
+export { backoffMs, consentState, eventIdFor, isUuid, keyKind, retryable, retryAfterMs, toConsent, trimHost, type ConsentInput, } from "./helpers.js";
+export { cleanExternalIds, cleanProperties } from "./properties.js";
+export { uuidv7 } from "./uuid.js";
+export { isDateTime, validateBatch, validateEvent, type Issue } from "./validate.js";