zklicensing 0.1.0-beta.2 → 0.1.0-beta.4

package/src/statsClient.ts

@@ -0,0 +1,235 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * statsClient.ts
+ *
+ * Browser-safe HTTP client for the vendor-facing keeper endpoints that back
+ * the dashboard: GET /stats, GET /transactions, and GET /apps/vendor/:addr.
+ *
+ * Types mirror the keeper's response shapes so a dashboard implementation
+ * (this repo's zklicensing.com dashboard or a third-party one) doesn't have
+ * to re-derive them. New optional fields on the server should be added here
+ * as `?:` so older clients still typecheck against a newer keeper.
+ */
+
+import type { CountryBreakdown } from './countryStats.js';
+import type { FiatRateSnapshot } from './licenseRecord.js';
+
+export type Tier = 'monthly' | 'yearly' | 'fiveYear' | 'perpetual';
+
+export type AppRecord = {
+  appId:                  string;
+  name:                   string;
+  description:            string;
+  longDescription?:       string;
+  category:               string;
+  website:                string;
+  // Absent on `status: 'not-deployed'` stub rows (returned by
+  // GET /apps/vendor/:addr?network=… for apps the vendor owns but hasn't
+  // deployed on the queried network). Present on every other projection.
+  zkAppAddress?:          string;
+  vendorAddress:          string;
+  priceMonthlyMina:       number;
+  priceYearlyMina:        number;
+  priceFiveYearMina:      number;
+  pricePerpetualMina:     number;
+  // Also absent on `status: 'not-deployed'` stub rows. See zkAppAddress note.
+  txHash?:                string;
+  verificationKeyHash?:   string;
+  logo?:                  string;
+  // Best favicon URL for the vendor's website, resolved server-side by the
+  // keeper (parses `<link rel="icon">` tags on the website). Undefined until
+  // the vendor's next edit for grandfathered apps — clients should fall back
+  // to `${host}/favicon.ico` in that case.
+  iconUrl?:               string;
+  tags?:                  string[];
+  contactEmail?:          string;
+  supportEmail?:          string;
+  country?:               string;
+  status?:                'pending' | 'active' | 'inactive' | 'rejected' | 'not-deployed';
+  rejectionReason?:       string;
+  createdAt:              string;
+  approvedAt?:            string;
+  // Which network this record projection is scoped to. Present on responses
+  // from GET /apps?network=… and GET /apps/vendor/:addr?network=… — the keeper
+  // stamps it so a dashboard rendering multiple projections doesn't have to
+  // track the query it made.
+  network?:               'devnet' | 'mainnet';
+  // Sibling networks this app is also deployed to. Empty or omitted when the
+  // app only exists on `network`. Dashboards use this to render "Also deploy
+  // to X →" / "Promote to X →" cross-origin CTAs.
+  alsoOnNetworks?:        ('devnet' | 'mainnet')[];
+  // Per-deployment sync bookkeeping, flattened from AppRecord.deployments[network]
+  // by the keeper's network-scoped list handlers.
+  firstEventSlot?:        number;
+  lastSyncedSlot?:        number;
+  onChainVersion?:        number;
+  deploymentHistory?:     unknown[];
+  pendingEdit?:           Partial<AppRecord> & { editedAt: string };
+  // Append-only audit trail of status transitions. Optional so older keepers
+  // that don't yet emit it still typecheck.
+  statusHistory?:         { status: string; at: string; actor: string; note?: string }[];
+  // Vendor legal / billing block — collected at registration for compliance
+  // (CRD Art. 6, e-Commerce Directive Art. 5) and reused in the vendor's
+  // tax-year CSV export. All optional here so older keepers that don't yet
+  // return these fields still typecheck. `country` (top-level above) is the
+  // billing country and pairs with `billingAddress` — the address struct
+  // intentionally omits a country field to avoid drift.
+  legalName?:             string;
+  billingAddress?:        { line1: string; line2?: string; city: string; postalCode: string };
+  invoiceEmail?:          string;
+  vatId?:                 string;
+  companyRegistrationRegistry?: string;
+  companyRegistrationNumber?:   string;
+  // Registration fee (in MINA) actually paid at deploy time. Stamped from
+  // the keeper's REGISTRATION_FEE constant when the record was created.
+  // Absent on pre-persistence records — consumers should fall back to the
+  // legacy flat 100 MINA fee for records without this field.
+  registrationFeeMina?:   number;
+};
+
+export type VendorStatsResponse = {
+  apps:               AppRecord[];
+  activeLicenses:     number;
+  totalLicenses:      number;
+  totalRevenueMina:   number;
+  pendingRevenueMina?: number;
+  // Vendor's post-fee share of refunded purchases, in MINA. Optional so older
+  // keepers (pre-refund-tracking) still typecheck against this SDK.
+  refundedRevenueMina?: number;
+  renewalRate:        number | null;
+  monthlyRevenueMina: { month: string; mina: number }[];
+  licensesByTier?:    { monthly: number; yearly: number; fiveYear: number; perpetual: number };
+  deltas:             { revenuePct: number | null };
+  countryBreakdown?:  CountryBreakdown;
+};
+
+export type Transaction = {
+  type:      'purchase' | 'renewal' | 'release' | 'refund';
+  appId:     string;
+  appName:   string;
+  // Only populated on the admin __all response — vendor-scoped queries omit it
+  // since the caller already knows the vendor from the query itself.
+  vendorAddress?: string;
+  tier:      Tier | null;
+  amountMina: number;
+  txHash:    string;
+  date:      string; // ISO
+  // Buyer's ISO-3166 alpha-2 country at purchase (present on purchase rows and
+  // any downstream renewal/refund/release rows for the same record). Optional
+  // for pre-country-capture legacy rows.
+  buyerCountry?: string;
+  // MINA→fiat rates snapshotted at the moment the underlying purchase/renewal
+  // confirmed — same fields as the receipt email. Missing on archive-replayed
+  // records and on rows created before the first successful CoinGecko fetch.
+  fiatSnapshot?: FiatRateSnapshot;
+};
+
+export type TransactionsResponse = { transactions: Transaction[] };
+
+export type VendorAppsResponse = { apps: AppRecord[] };
+
+function baseUrl(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+// Admin __all mode: pass `adminToken` and omit `vendorAddress` (or pass '__all').
+// Fetches aggregate over every registered app. Server gates with Bearer auth.
+// tzOffsetMinutes: signed minutes east of UTC — shifts tax-year cutovers on the
+// countryBreakdown so a UK vendor's 2026 doesn't include a Dec 31 23:30 PST
+// purchase. Default omitted → UTC bucketing preserved for existing callers.
+export async function fetchVendorStats(opts: {
+  keeperUrl:        string;
+  vendorAddress:    string;
+  network:          'devnet' | 'mainnet';
+  adminToken?:      string;
+  // Vendor dashboard-session bearer for the per-vendor read path. Mutually
+  // exclusive with adminToken (adminToken wins if both set — the '__all'
+  // path never has a session).
+  vendorSessionToken?: string;
+  tzOffsetMinutes?: number;
+  fetcher?:         typeof fetch;
+  signal?:          AbortSignal;
+}): Promise<VendorStatsResponse | null> {
+  const fetcher = opts.fetcher ?? fetch;
+  const headers: Record<string, string> = {};
+  if (opts.adminToken) headers.Authorization = `Bearer ${opts.adminToken}`;
+  else if (opts.vendorSessionToken) headers.Authorization = `VendorSession ${opts.vendorSessionToken}`;
+  const tzQ = typeof opts.tzOffsetMinutes === 'number' ? `&tz=${opts.tzOffsetMinutes}` : '';
+  const resp = await fetcher(
+    `${baseUrl(opts.keeperUrl)}/stats?vendor=${encodeURIComponent(opts.vendorAddress)}&network=${opts.network}${tzQ}`,
+    { signal: opts.signal, headers },
+  );
+  if (!resp.ok) return null;
+  return await resp.json() as VendorStatsResponse;
+}
+
+export async function fetchTransactions(opts: {
+  keeperUrl:      string;
+  vendorAddress:  string;
+  network:        'devnet' | 'mainnet';
+  adminToken?:    string;
+  vendorSessionToken?: string;
+  // Rolling window in days. Default 30. Ignored when both `from` and `to` are
+  // set (explicit range wins) — used for the dashboard's "last N days" view.
+  days?:          number;
+  // Explicit inclusive-start / exclusive-end ISO dates (YYYY-MM-DD). When both
+  // are set the server filters to [from, to) instead of the rolling window.
+  // Used by the CSV export to fetch an exact tax year without over-fetching.
+  from?:          string;
+  to?:            string;
+  fetcher?:       typeof fetch;
+  signal?:        AbortSignal;
+}): Promise<TransactionsResponse | null> {
+  const fetcher = opts.fetcher ?? fetch;
+  const headers: Record<string, string> = {};
+  if (opts.adminToken) headers.Authorization = `Bearer ${opts.adminToken}`;
+  else if (opts.vendorSessionToken) headers.Authorization = `VendorSession ${opts.vendorSessionToken}`;
+  const qs = new URLSearchParams({ vendor: opts.vendorAddress, network: opts.network });
+  if (opts.from && opts.to) {
+    qs.set('from', opts.from);
+    qs.set('to', opts.to);
+  } else {
+    qs.set('days', String(opts.days ?? 30));
+  }
+  const resp = await fetcher(
+    `${baseUrl(opts.keeperUrl)}/transactions?${qs.toString()}`,
+    { signal: opts.signal, headers },
+  );
+  if (!resp.ok) return null;
+  return await resp.json() as TransactionsResponse;
+}
+
+// Admin all-apps mode: pass `adminToken` and set `vendorAddress` to '__all'.
+// Hits GET /apps (no auth needed today; the admin overload just uses a
+// different URL) so vendors visiting their own dashboard still hit the same
+// per-vendor endpoint.
+export async function fetchVendorApps(opts: {
+  keeperUrl:      string;
+  vendorAddress:  string;
+  adminToken?:    string;
+  vendorSessionToken?: string;
+  // Network scope for the vendor projection. Required for the per-vendor path
+  // — the keeper returns records projected against `deployments[network]` plus
+  // stub rows for apps the vendor owns but hasn't deployed on this network
+  // (status: 'not-deployed'). Omitted only in admin __all mode.
+  network?:       'devnet' | 'mainnet';
+  fetcher?:       typeof fetch;
+  signal?:        AbortSignal;
+}): Promise<VendorAppsResponse | null> {
+  const fetcher = opts.fetcher ?? fetch;
+  const headers: Record<string, string> = {};
+  if (opts.adminToken) headers.Authorization = `Bearer ${opts.adminToken}`;
+  else if (opts.vendorSessionToken) headers.Authorization = `VendorSession ${opts.vendorSessionToken}`;
+  const isAdminAll = opts.adminToken && opts.vendorAddress === '__all';
+  if (!isAdminAll && !opts.network) {
+    throw new Error("fetchVendorApps: `network` is required for the per-vendor path");
+  }
+  const url = isAdminAll
+    ? `${baseUrl(opts.keeperUrl)}/apps?all=1`
+    : `${baseUrl(opts.keeperUrl)}/apps/vendor/${encodeURIComponent(opts.vendorAddress)}?network=${opts.network}`;
+  const resp = await fetcher(url, { signal: opts.signal, headers });
+  if (!resp.ok) return null;
+  return await resp.json() as VendorAppsResponse;
+}