@customyai/customy-sdk 0.1.0 → 0.2.0

package/dist/server.d.ts

@@ -0,0 +1,164 @@
+import { CustomyPlatformConfiguration, MachineTokenProvider } from '@customyai/customy-access/server';
+import { CustomySend } from '@customyai/send-sdk';
+import { CustomyLinks } from '@customyai/links-sdk';
+import { k as CustomySdkKey, e as CustomyProductClient } from './portfolio-Bk9cn8h4.js';
+
+type CustomerDataEventType = "track" | "identify" | "group" | "page" | "screen" | "alias";
+interface CustomerDataEvent {
+    messageId?: string;
+    type: CustomerDataEventType;
+    event?: string;
+    userId?: string;
+    anonymousId?: string;
+    groupId?: string;
+    timestamp?: string | Date;
+    schemaVersion?: string;
+    properties?: Record<string, unknown>;
+    traits?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+    consent?: Record<string, unknown>;
+}
+interface CustomerDataClientConfig {
+    collectUrl: string;
+    /** Write key de la fuente (navegador y apps sin identidad de servidor). */
+    writeKey?: string;
+    /**
+     * En servidor, en lugar del write key: un token de máquina de Customy Access
+     * con audiencia `customy-data` y scope `data:collect` (la identidad única de
+     * la app; `createMachineTokenProvider` de `@customyai/customy-access/server`).
+     * Data resuelve la fuente de la app a partir de los claims firmados.
+     */
+    accessToken?: () => Promise<string>;
+    fetchImpl?: typeof fetch;
+    maxRetries?: number;
+    retryBaseMs?: number;
+    timeoutMs?: number;
+    maxBatchSize?: number;
+    maxQueueSize?: number;
+    redactFields?: string[];
+    beforeSend?: (event: CustomerDataEvent) => CustomerDataEvent | null;
+    now?: () => Date;
+    idFactory?: () => string;
+    onError?: (error: Error, events: CustomerDataEvent[]) => void;
+}
+interface CustomerDataBatchResponse {
+    accepted: number;
+    deduplicated: number;
+    quarantined: number;
+    results: Array<Record<string, unknown>>;
+}
+/**
+ * Public/browser-safe customer data client. Tenant scope is derived from the
+ * source write key by customy-data; callers cannot select organization,
+ * project or environment in the payload.
+ */
+declare class CustomyCustomerDataClient {
+    private readonly config;
+    private readonly fetchImpl;
+    private readonly maxRetries;
+    private readonly retryBaseMs;
+    private readonly timeoutMs;
+    private readonly maxBatchSize;
+    private readonly maxQueueSize;
+    private readonly redactFields;
+    private readonly now;
+    private readonly idFactory;
+    private queue;
+    private flushing;
+    private inFlightCount;
+    constructor(config: CustomerDataClientConfig);
+    event(input: CustomerDataEvent): CustomerDataEvent;
+    enqueue(input: CustomerDataEvent): number;
+    send(input: CustomerDataEvent): Promise<Record<string, unknown>>;
+    track(event: string, properties: Record<string, unknown>, identity: Pick<CustomerDataEvent, "userId" | "anonymousId" | "groupId" | "context" | "consent">): Promise<Record<string, unknown>>;
+    identify(traits: Record<string, unknown>, identity: Pick<CustomerDataEvent, "userId" | "anonymousId" | "context" | "consent">): Promise<Record<string, unknown>>;
+    group(traits: Record<string, unknown>, identity: Pick<CustomerDataEvent, "groupId" | "userId" | "anonymousId" | "context" | "consent">): Promise<Record<string, unknown>>;
+    page(properties: Record<string, unknown>, identity: Pick<CustomerDataEvent, "userId" | "anonymousId" | "context" | "consent">): Promise<Record<string, unknown>>;
+    screen(properties: Record<string, unknown>, identity: Pick<CustomerDataEvent, "userId" | "anonymousId" | "context" | "consent">): Promise<Record<string, unknown>>;
+    alias(userId: string, previousId: string, options?: Pick<CustomerDataEvent, "context" | "consent">): Promise<Record<string, unknown>>;
+    flush(): Promise<CustomerDataBatchResponse>;
+    private request;
+}
+
+/**
+ * Consumo de una app en Customy Billing con su identidad de Customy Access
+ * (`POST /v1/apps/usage`). El token de máquina, con audiencia `customy-billing`
+ * y scope `billing:usage:report`, fija la organización y la app: el cuerpo solo
+ * lleva el meter, la cantidad y una clave de idempotencia por evento.
+ */
+type AppUsageEvent = {
+    /** Meter declarado por la app, p. ej. `coach.runs`. */
+    meter: string;
+    quantity: number;
+    /** Única por evento: reintentar con la misma clave no suma dos veces. */
+    idempotencyKey: string;
+    occurredAt?: string | Date;
+};
+type AppUsageResult = {
+    accepted: number;
+    events: Array<{
+        meter: string;
+        idempotencyKey: string;
+        id: string;
+        deduplicated: boolean;
+    }>;
+};
+type AppUsageClientConfig = {
+    /** URL de Billing del entorno (discovery: `products.billing.base_url`). */
+    baseUrl: string;
+    /** Proveedor de tokens de Access (`createMachineTokenProvider` de `@customyai/customy-access/server`). */
+    accessToken: () => Promise<string>;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+};
+declare class AppUsageClient {
+    private readonly config;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(config: AppUsageClientConfig);
+    /** Reporta hasta 100 eventos de consumo en una llamada. */
+    report(events: AppUsageEvent[]): Promise<AppUsageResult>;
+}
+
+/**
+ * @customyai/customy-sdk/server — `createCustomy()`: una sola identidad de app para todo el ecosistema.
+ *
+ * Lee el discovery del issuer (`/.well-known/customy-configuration`), crea un
+ * proveedor de tokens de máquina por audiencia de producto y entrega los
+ * clientes de cada producto ya apuntando a su URL y con su proveedor. No añade
+ * transporte propio: compone los SDK de cada servicio. Solo para servidor —
+ * usa el secreto de la app.
+ *
+ *   const customy = await createCustomy({ issuer, clientId, clientSecret });
+ *   await customy.send.emails.send({ ... });
+ *   await customy.billing.report([{ meter: "coach.runs", quantity: 1, idempotencyKey }]);
+ *   await customy.product("crm").get("/v1/contacts");
+ */
+
+type CreateCustomyOptions = {
+    /** Issuer de Customy Access del entorno, p. ej. `https://access-api.customy.ai`. */
+    issuer: string;
+    clientId: string;
+    clientSecret: string;
+    /** Scopes por producto (clave del discovery). Sin entrada, los del cliente. */
+    scopes?: Partial<Record<string, readonly string[]>>;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    /** Opciones extra del cliente de Data (colas, redacción, `onError`…). */
+    data?: Omit<CustomerDataClientConfig, "collectUrl" | "writeKey" | "accessToken" | "fetchImpl">;
+};
+type Customy = {
+    readonly platform: CustomyPlatformConfiguration;
+    /** Proveedor de tokens de máquina para la audiencia de un producto del discovery. */
+    token(product: string): MachineTokenProvider;
+    /** Cliente HTTP genérico de un producto, con su URL y su proveedor de tokens. */
+    product(product: CustomySdkKey): CustomyProductClient;
+    readonly send: CustomySend;
+    readonly links: CustomyLinks;
+    readonly data: CustomyCustomerDataClient;
+    readonly billing: AppUsageClient;
+};
+declare function createCustomy(options: CreateCustomyOptions): Promise<Customy>;
+
+export { type CreateCustomyOptions, type Customy, createCustomy };

package/dist/server.mjs

@@ -0,0 +1,430 @@
+import { CustomySdkError, CustomyProductClient } from './chunk-2TLSPDBG.mjs';
+import { discoverPlatform, createMachineTokenProvider } from '@customyai/customy-access/server';
+import { CustomySend } from '@customyai/send-sdk';
+import { CustomyLinks } from '@customyai/links-sdk';
+
+// src/vendor/sdk-data.ts
+var CUSTOMY_DATA_SDK_VERSION = "0.3.1";
+var DataSdkError = class extends Error {
+  constructor(message, statusCode, response) {
+    super(message);
+    this.statusCode = statusCode;
+    this.response = response;
+    this.name = "DataSdkError";
+  }
+  statusCode;
+  response;
+};
+var CustomyCustomerDataClient = class {
+  constructor(config) {
+    this.config = config;
+    if (!config.collectUrl || !config.writeKey && !config.accessToken) {
+      throw new Error("collectUrl and writeKey (or accessToken) are required");
+    }
+    const fetchImpl = config.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) throw new Error("fetch is required. Pass fetchImpl in non-browser runtimes.");
+    this.fetchImpl = fetchImpl;
+    this.maxRetries = config.maxRetries ?? 3;
+    this.retryBaseMs = config.retryBaseMs ?? 250;
+    this.timeoutMs = config.timeoutMs ?? 1e4;
+    this.maxBatchSize = Math.min(1e3, Math.max(1, config.maxBatchSize ?? 100));
+    this.maxQueueSize = Math.max(1, config.maxQueueSize ?? 1e4);
+    this.redactFields = new Set(config.redactFields ?? []);
+    this.now = config.now ?? (() => /* @__PURE__ */ new Date());
+    this.idFactory = config.idFactory ?? randomId;
+  }
+  config;
+  fetchImpl;
+  maxRetries;
+  retryBaseMs;
+  timeoutMs;
+  maxBatchSize;
+  maxQueueSize;
+  redactFields;
+  now;
+  idFactory;
+  queue = [];
+  flushing = false;
+  inFlightCount = 0;
+  event(input) {
+    rejectCustomerDataTenantFields(input);
+    let normalized = {
+      ...input,
+      messageId: input.messageId ?? this.idFactory(),
+      timestamp: normalizeDate(input.timestamp ?? this.now()),
+      schemaVersion: input.schemaVersion ?? "1.0",
+      properties: input.properties ?? {},
+      traits: input.traits ?? {},
+      context: {
+        ...input.context,
+        library: {
+          name: "./sdk-data",
+          version: CUSTOMY_DATA_SDK_VERSION
+        }
+      },
+      consent: input.consent ?? {}
+    };
+    validateCustomerDataEvent(normalized);
+    normalized = redactCustomerDataEvent(normalized, this.redactFields);
+    if (this.config.beforeSend) {
+      const candidate = this.config.beforeSend(cloneCustomerDataEvent(normalized));
+      if (!candidate) throw new Error("Event blocked by beforeSend");
+      rejectCustomerDataTenantFields(candidate);
+      normalized = redactCustomerDataEvent(candidate, this.redactFields);
+      validateCustomerDataEvent(normalized);
+    }
+    return normalized;
+  }
+  enqueue(input) {
+    if (this.queue.length + this.inFlightCount >= this.maxQueueSize) {
+      throw new Error("Customer data queue is full");
+    }
+    const normalized = this.event(input);
+    if (this.queue.length + this.inFlightCount >= this.maxQueueSize) {
+      throw new Error("Customer data queue is full");
+    }
+    this.queue.push(normalized);
+    return this.queue.length;
+  }
+  async send(input) {
+    return this.request("event", this.event(input));
+  }
+  async track(event, properties, identity) {
+    return this.send({ type: "track", event, properties, ...identity });
+  }
+  async identify(traits, identity) {
+    return this.send({ type: "identify", traits, ...identity });
+  }
+  async group(traits, identity) {
+    return this.send({ type: "group", traits, ...identity });
+  }
+  async page(properties, identity) {
+    return this.send({ type: "page", properties, ...identity });
+  }
+  async screen(properties, identity) {
+    return this.send({ type: "screen", properties, ...identity });
+  }
+  async alias(userId, previousId, options = {}) {
+    return this.send({
+      type: "alias",
+      userId,
+      anonymousId: previousId,
+      properties: { previousId },
+      ...options
+    });
+  }
+  async flush() {
+    if (this.flushing) throw new Error("A customer data flush is already in progress");
+    if (this.queue.length === 0) {
+      return {
+        accepted: 0,
+        deduplicated: 0,
+        quarantined: 0,
+        results: []
+      };
+    }
+    this.flushing = true;
+    const pending = this.queue;
+    this.inFlightCount = pending.length;
+    this.queue = [];
+    const aggregate = {
+      accepted: 0,
+      deduplicated: 0,
+      quarantined: 0,
+      results: []
+    };
+    try {
+      for (let offset = 0; offset < pending.length; offset += this.maxBatchSize) {
+        const batch = pending.slice(offset, offset + this.maxBatchSize);
+        const response = await this.request("batch", {
+          batch
+        });
+        aggregate.accepted += Number(response.accepted ?? 0);
+        aggregate.deduplicated += Number(response.deduplicated ?? 0);
+        aggregate.quarantined += Number(response.quarantined ?? 0);
+        aggregate.results.push(...response.results ?? []);
+      }
+      this.flushing = false;
+      this.inFlightCount = 0;
+      return aggregate;
+    } catch (error) {
+      this.queue = [...pending, ...this.queue];
+      this.flushing = false;
+      this.inFlightCount = 0;
+      const normalized = error instanceof Error ? error : new Error(String(error));
+      this.config.onError?.(normalized, pending);
+      throw normalized;
+    }
+  }
+  async request(path, body) {
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
+      const controller = typeof AbortController !== "undefined" ? new AbortController() : void 0;
+      const timer = controller ? setTimeout(() => controller.abort(), this.timeoutMs) : void 0;
+      try {
+        const response = await this.fetchImpl(`${this.config.collectUrl.replace(/\/$/, "")}/v1/collect/${path}`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            ...this.config.accessToken ? { authorization: `Bearer ${await this.config.accessToken()}` } : { "x-write-key": this.config.writeKey }
+          },
+          body: JSON.stringify(body),
+          signal: controller?.signal
+        });
+        const text = await response.text();
+        const parsed = text ? safeJson(text) : {};
+        if (!response.ok) {
+          throw new DataSdkError(`Customy customer data collection failed with HTTP ${response.status}`, response.status, parsed);
+        }
+        validateCustomerDataAcknowledgement(
+          path,
+          parsed,
+          path === "batch" ? body.batch.length : 1,
+          response.status
+        );
+        return parsed;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (!isRetryableError(lastError) || attempt >= this.maxRetries) throw lastError;
+        await sleep(this.retryBaseMs * Math.pow(2, attempt));
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+    }
+    throw lastError ?? new Error("Unknown customer data collection failure");
+  }
+};
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function collectionOutcome(value) {
+  if (!isRecord(value)) return void 0;
+  const hasId = (id) => typeof id === "string" && id.trim().length > 0;
+  if (value.quarantined === true) {
+    return value.accepted === false && value.deduplicated === false && hasId(value.quarantineId) ? "quarantined" : void 0;
+  }
+  if (value.quarantined !== void 0 && value.quarantined !== false) return void 0;
+  if (!hasId(value.eventId)) return void 0;
+  if (value.accepted === true && value.deduplicated === false) return "accepted";
+  if (value.accepted === false && value.deduplicated === true) return "deduplicated";
+  return void 0;
+}
+function validateCustomerDataAcknowledgement(path, value, expectedCount, status) {
+  const reject = () => {
+    throw new DataSdkError("Customy customer data collection returned an invalid acknowledgement", status);
+  };
+  if (path === "event") {
+    const outcome = collectionOutcome(value);
+    if (outcome !== "accepted" && outcome !== "deduplicated") reject();
+    return;
+  }
+  if (!isRecord(value) || !Array.isArray(value.results) || value.results.length !== expectedCount) return reject();
+  const counts = { accepted: 0, deduplicated: 0, quarantined: 0 };
+  for (const result of value.results) {
+    const outcome = collectionOutcome(result);
+    if (!outcome) return reject();
+    counts[outcome] += 1;
+  }
+  for (const key of ["accepted", "deduplicated", "quarantined"]) {
+    if (!Number.isSafeInteger(value[key]) || value[key] !== counts[key]) reject();
+  }
+}
+var CUSTOMER_DATA_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "track",
+  "identify",
+  "group",
+  "page",
+  "screen",
+  "alias"
+]);
+var FORBIDDEN_CUSTOMER_DATA_TENANT_FIELDS = [
+  "tenantId",
+  "organizationId",
+  "projectId",
+  "environmentId"
+];
+function validateCustomerDataEvent(event) {
+  if (!CUSTOMER_DATA_EVENT_TYPES.has(event.type)) {
+    throw new Error("Type must be track, identify, group, page, screen or alias");
+  }
+  if (!event.userId && !event.anonymousId && !event.groupId) {
+    throw new Error("At least one userId, anonymousId or groupId is required");
+  }
+  if (event.type === "track" && !event.event) {
+    throw new Error("Track calls require an event name");
+  }
+}
+function rejectCustomerDataTenantFields(event) {
+  const payload = event;
+  const forbidden = FORBIDDEN_CUSTOMER_DATA_TENANT_FIELDS.filter(
+    (key) => Object.prototype.hasOwnProperty.call(payload, key)
+  );
+  if (forbidden.length > 0) {
+    throw new Error(
+      `Tenant scope is derived from the write key; forbidden fields: ${forbidden.join(", ")}`
+    );
+  }
+}
+function cloneCustomerDataEvent(event) {
+  return JSON.parse(JSON.stringify(event));
+}
+function redactCustomerDataEvent(event, fields) {
+  return redactCustomerDataValue(event, fields);
+}
+function redactCustomerDataValue(value, fields) {
+  if (value instanceof Date) return value.toISOString();
+  if (Array.isArray(value)) {
+    return value.map((entry) => redactCustomerDataValue(entry, fields));
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        key,
+        fields.has(key) ? "[REDACTED]" : redactCustomerDataValue(entry, fields)
+      ])
+    );
+  }
+  return value;
+}
+function normalizeDate(value) {
+  return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
+}
+function isRetryableError(error) {
+  if (error instanceof DataSdkError) {
+    return !error.statusCode || error.statusCode >= 500 || error.statusCode === 429;
+  }
+  return true;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function randomId() {
+  if (globalThis.crypto?.randomUUID) return globalThis.crypto.randomUUID();
+  if (globalThis.crypto?.getRandomValues) {
+    const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+    bytes[6] = bytes[6] & 15 | 64;
+    bytes[8] = bytes[8] & 63 | 128;
+    const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0"));
+    return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
+  }
+  return `evt_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
+}
+function safeJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}
+
+// src/vendor/app-usage.ts
+var AppUsageError = class extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "AppUsageError";
+  }
+  status;
+  code;
+};
+var AppUsageClient = class {
+  constructor(config) {
+    this.config = config;
+    if (!config?.baseUrl || typeof config.accessToken !== "function") throw new Error("AppUsageClient: baseUrl and accessToken are required");
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.fetchImpl = config.fetch ?? globalThis.fetch;
+    this.timeoutMs = config.timeoutMs ?? 1e4;
+  }
+  config;
+  baseUrl;
+  fetchImpl;
+  timeoutMs;
+  /** Reporta hasta 100 eventos de consumo en una llamada. */
+  async report(events) {
+    if (events.length === 0 || events.length > 100) throw new Error("AppUsageClient: between 1 and 100 events per call");
+    const response = await this.fetchImpl(`${this.baseUrl}/v1/apps/usage`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${await this.config.accessToken()}`, "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({
+        events: events.map((event) => ({
+          meter: event.meter,
+          quantity: event.quantity,
+          idempotencyKey: event.idempotencyKey,
+          ...event.occurredAt ? { occurredAt: new Date(event.occurredAt).toISOString() } : {}
+        }))
+      }),
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok) throw new AppUsageError(response.status, String(body.error ?? `HTTP_${response.status}`), String(body.message ?? "Usage report failed"));
+    return body;
+  }
+};
+
+// src/server.ts
+async function createCustomy(options) {
+  if (!options.clientId || !options.clientSecret) throw new Error("CUSTOMY_MACHINE_CREDENTIALS_REQUIRED");
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const platform = await discoverPlatform(options.issuer, fetchImpl);
+  const providers = /* @__PURE__ */ new Map();
+  const clients = /* @__PURE__ */ new Map();
+  function entry(product) {
+    const found = platform.products[product];
+    if (!found) throw new Error(`CUSTOMY_PRODUCT_NOT_DISCOVERED: ${product}`);
+    return found;
+  }
+  function token(product) {
+    let provider = providers.get(product);
+    if (!provider) {
+      provider = createMachineTokenProvider({
+        issuer: platform.issuer,
+        tokenEndpoint: platform.tokenEndpoint,
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        audience: entry(product).audience,
+        scopes: options.scopes?.[product],
+        fetch: fetchImpl
+      });
+      providers.set(product, provider);
+    }
+    return provider;
+  }
+  function once(key, build) {
+    if (!clients.has(key)) clients.set(key, build());
+    return clients.get(key);
+  }
+  return {
+    platform,
+    token,
+    product(product) {
+      if (!platform.products[product]) throw new CustomySdkError(product, 0, "SDK_PRODUCT_NOT_DISCOVERED");
+      return once(`product:${product}`, () => new CustomyProductClient(product, {
+        baseUrl: entry(product).baseUrl,
+        accessToken: token(product),
+        fetch: options.fetch,
+        timeoutMs: options.timeoutMs
+      }));
+    },
+    get send() {
+      return once("send", () => new CustomySend(token("send"), { baseUrl: entry("send").baseUrl, fetch: options.fetch, timeoutMs: options.timeoutMs }));
+    },
+    get links() {
+      return once("links", () => new CustomyLinks({ apiKey: token("links"), baseUrl: entry("links").baseUrl, fetch: options.fetch, timeoutMs: options.timeoutMs }));
+    },
+    get data() {
+      return once("data", () => new CustomyCustomerDataClient({
+        ...options.data,
+        collectUrl: entry("data").baseUrl,
+        accessToken: token("data"),
+        fetchImpl: options.fetch,
+        timeoutMs: options.timeoutMs
+      }));
+    },
+    get billing() {
+      return once("billing", () => new AppUsageClient({ baseUrl: entry("billing").baseUrl, accessToken: token("billing"), fetch: options.fetch, timeoutMs: options.timeoutMs }));
+    }
+  };
+}
+
+export { createCustomy };