@trillboards/api-client 0.2.0 → 0.3.0

package/dist/index.mjs

@@ -74,6 +74,47 @@ var VERSION = "0.1.3";
 
 // src/http.ts
 var PUBLIC_PATHS = ["/v1/errors", "/v1/changelog", "/api/discover", "/v1/health"];
+function isRetryable(err) {
+  if (err instanceof TrillboardsError) {
+    return err.statusCode === 429 || err.statusCode >= 500;
+  }
+  if (err instanceof TypeError) return true;
+  return false;
+}
+function computeBackoffMs(attempt, baseMs, err) {
+  if (err instanceof TrillboardsError && err.retryAfter != null && err.retryAfter > 0) {
+    return err.retryAfter * 1e3;
+  }
+  const exponential = baseMs * Math.pow(2, attempt);
+  return Math.floor(Math.random() * exponential);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function retryWithBackoff(operation, opts = {}) {
+  const retries = opts.retries ?? 6;
+  const baseMs = opts.baseMs ?? 1e3;
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    try {
+      return await operation();
+    } catch (err) {
+      lastError = err;
+      if (!isRetryable(err) || attempt === retries) {
+        throw err;
+      }
+      if (opts.onAttemptError) {
+        try {
+          opts.onAttemptError(attempt + 1, err);
+        } catch {
+        }
+      }
+      const delayMs = computeBackoffMs(attempt, baseMs, err);
+      await sleep(delayMs);
+    }
+  }
+  throw lastError;
+}
 var HttpClient = class {
   constructor(config) {
     this.config = config;
@@ -124,17 +165,28 @@ var HttpClient = class {
   get(path, opts) {
     return this.request("GET", path, { params: opts?.params });
   }
-  post(path, body) {
-    return this.request("POST", path, { body });
+  /**
+   * POST / PUT / PATCH / DELETE auto-retry on 429 + 5xx + network TypeError
+   * via `retryWithBackoff()`. Callers can opt into observability by passing
+   * `retry.onAttemptError` to receive a callback per transient failure.
+   *
+   * The retry behavior is identical across all four methods because all of
+   * them are state-changing operations subject to the same transient-failure
+   * classes (rate limit, upstream-down, network-flap). The wire idempotency
+   * of POST vs DELETE is enforced server-side via Idempotency-Key headers,
+   * which the caller can attach via `opts.headers`.
+   */
+  post(path, body, opts) {
+    return retryWithBackoff(() => this.request("POST", path, { body, headers: opts?.headers }), opts?.retry);
   }
-  put(path, body) {
-    return this.request("PUT", path, { body });
+  put(path, body, opts) {
+    return retryWithBackoff(() => this.request("PUT", path, { body, headers: opts?.headers }), opts?.retry);
   }
-  patch(path, body) {
-    return this.request("PATCH", path, { body });
+  patch(path, body, opts) {
+    return retryWithBackoff(() => this.request("PATCH", path, { body, headers: opts?.headers }), opts?.retry);
   }
-  delete(path) {
-    return this.request("DELETE", path);
+  delete(path, opts) {
+    return retryWithBackoff(() => this.request("DELETE", path, { headers: opts?.headers }), opts?.retry);
   }
   buildUrl(path, params) {
     const base = `${this.config.baseUrl}${path}`;
@@ -195,9 +247,20 @@ var DevicesClient = class {
   async delete(deviceId) {
     return this.http.delete(`/v1/partner/device/${deviceId}`);
   }
-  /** Send heartbeat for a device. */
-  async heartbeat(deviceId, body) {
-    return this.http.post(`/v1/partner/device/${deviceId}/heartbeat`, body ?? {});
+  /**
+   * Send heartbeat for a device.
+   *
+   * Auto-retries on 429 + 5xx + network TypeError via the shared
+   * retryWithBackoff() helper (see http.ts). Pass `opts.retry.onAttemptError`
+   * to observe transient failures (e.g. emit an `upload_error` event from
+   * the CTV SDK without coupling the retry loop to its event emitter).
+   */
+  async heartbeat(deviceId, body, opts) {
+    return this.http.post(
+      `/v1/partner/device/${deviceId}/heartbeat`,
+      body ?? {},
+      { retry: opts?.retry }
+    );
   }
 };
 
@@ -381,31 +444,145 @@ var TrillboardsClient = class {
     this.billing = new BillingClient(this._http);
   }
 };
-function constructEvent(payload, signature, secret) {
+var DEFAULT_TOLERANCE_SECONDS = 300;
+function parseSignatureHeader(rawSig) {
+  const versions = /* @__PURE__ */ new Map();
+  let timestamp;
+  let legacy;
+  const trimmed = rawSig.trim();
+  if (trimmed.startsWith("sha256=")) {
+    legacy = trimmed.slice("sha256=".length);
+    return { timestamp, versions, legacy };
+  }
+  for (const part of trimmed.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq < 0) continue;
+    const key = part.slice(0, eq).trim();
+    const value = part.slice(eq + 1).trim();
+    if (!key || !value) continue;
+    if (key === "t") {
+      const ts = Number(value);
+      if (Number.isFinite(ts)) timestamp = ts;
+    } else if (/^v\d+$/.test(key)) {
+      versions.set(key, value);
+    }
+  }
+  return { timestamp, versions, legacy };
+}
+function getHeader(headers, name) {
+  const lc = name.toLowerCase();
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() === lc) {
+      const v = headers[key];
+      if (Array.isArray(v)) return v[0];
+      return v;
+    }
+  }
+  return void 0;
+}
+function constantTimeEqual(a, b) {
+  const aBuf = Buffer.from(a, "utf8");
+  const bBuf = Buffer.from(b, "utf8");
+  if (aBuf.length !== bBuf.length) return false;
+  return timingSafeEqual(aBuf, bBuf);
+}
+function authError(message) {
+  return new TrillboardsError({
+    type: "authentication_error",
+    code: "webhook_signature_invalid",
+    message,
+    statusCode: 401
+  });
+}
+function constructEvent(payload, headers, secret, opts = {}) {
+  let signatureHeader;
+  let timestampHeader;
+  if (typeof headers === "string") {
+    signatureHeader = headers;
+  } else if (headers && typeof headers === "object") {
+    signatureHeader = getHeader(headers, "X-Trillboards-Signature");
+    timestampHeader = getHeader(headers, "X-Trillboards-Timestamp");
+  }
+  if (!signatureHeader) {
+    throw authError("Missing X-Trillboards-Signature header.");
+  }
   const payloadStr = typeof payload === "string" ? payload : payload.toString("utf8");
-  const expectedSignature = createHmac("sha256", secret).update(payloadStr).digest("hex");
-  const sigBuffer = Buffer.from(signature, "utf8");
-  const expectedBuffer = Buffer.from(expectedSignature, "utf8");
-  if (sigBuffer.length !== expectedBuffer.length || !timingSafeEqual(sigBuffer, expectedBuffer)) {
-    throw new TrillboardsError({
-      type: "authentication_error",
-      code: "webhook_signature_invalid",
-      message: "Webhook signature verification failed. The payload may have been tampered with.",
-      statusCode: 401
-    });
+  const parsed = parseSignatureHeader(signatureHeader);
+  let ts = parsed.timestamp;
+  if (ts === void 0 && timestampHeader) {
+    const fromHeader = Number(timestampHeader);
+    if (Number.isFinite(fromHeader)) ts = fromHeader;
+  }
+  if (ts === void 0 || !Number.isFinite(ts)) {
+    throw authError(
+      "Webhook signature missing timestamp. Provide either `t=<unix_seconds>` inside X-Trillboards-Signature OR a separate X-Trillboards-Timestamp header."
+    );
+  }
+  const tolerance = opts.tolerance ?? DEFAULT_TOLERANCE_SECONDS;
+  const now = opts.nowSec ?? Math.floor(Date.now() / 1e3);
+  if (Math.abs(now - ts) > tolerance) {
+    throw authError(
+      `Webhook timestamp ${ts} outside tolerance window of ${tolerance}s (now ${now}). Possible replay attack.`
+    );
+  }
+  const v1Expected = createHmac("sha256", secret).update(`${ts}.${payloadStr}`).digest("hex");
+  const v0Expected = createHmac("sha256", secret).update(payloadStr).digest("hex");
+  const v1Provided = parsed.versions.get("v1");
+  const v0Provided = parsed.versions.get("v0");
+  if (v1Provided) {
+    if (constantTimeEqual(v1Provided, v1Expected)) {
+      return JSON.parse(payloadStr);
+    }
+    throw authError(
+      "Webhook v1 signature verification failed. The payload may have been tampered with, or your webhook secret may be incorrect."
+    );
+  }
+  if (v0Provided && constantTimeEqual(v0Provided, v0Expected)) {
+    return JSON.parse(payloadStr);
+  }
+  if (parsed.legacy) {
+    if (constantTimeEqual(parsed.legacy, v1Expected)) {
+      return JSON.parse(payloadStr);
+    }
+    if (constantTimeEqual(parsed.legacy, v0Expected)) {
+      return JSON.parse(payloadStr);
+    }
+  }
+  throw authError(
+    "Webhook signature verification failed. The payload may have been tampered with, or your webhook secret may be incorrect."
+  );
+}
+var legacyWarned = false;
+function constructEventLegacy(payload, signature, secret) {
+  if (!legacyWarned) {
+    console.warn(
+      "[@trillboards/api-client] constructEventLegacy is deprecated and unsafe (no replay protection). Migrate to Webhooks.constructEvent(payload, req.headers, secret). See https://api.trillboards.com/docs/integrations/webhook-signature-verification.md"
+    );
+    legacyWarned = true;
+  }
+  const payloadStr = typeof payload === "string" ? payload : payload.toString("utf8");
+  const expected = createHmac("sha256", secret).update(payloadStr).digest("hex");
+  if (!constantTimeEqual(signature, expected)) {
+    throw authError(
+      "Legacy webhook signature mismatch. If your server has been upgraded to the compound-header emitter, switch to Webhooks.constructEvent instead."
+    );
   }
   return JSON.parse(payloadStr);
 }
-var Webhooks = { constructEvent };
+var Webhooks = {
+  constructEvent,
+  constructEventLegacy,
+  parseSignatureHeader
+};
 
 // src/generated/index.ts
 var generatedTypes = {
-  schemaCount: 67,
-  operationCount: 132,
-  schemas: ["Ad", "AdSettings", "AudienceAnalyticsResponse", "AudienceExportResponse", "AudienceMetricsResponse", "AudienceSegment", "BatchResult", "BleScanResultData", "ChangelogEntry", "ChangelogResponse", "ContentPreferencesInput", "ContentPreferencesResponse", "ContentPreset", "DashboardResponse", "DemographicsResponse", "Device", "DeviceCapabilityPayload", "DeviceSummary", "DisplaySettingsInput", "DisplaySettingsResponse", "EarningsBreakdownResponse", "EarningsResponse", "Error", "HeaderBiddingSettings", "HttpProbeResult", "MdnsNetworkDevice", "Pagination", "Partner", "PartnerAdDeliveryProfile", "PartnerDefaultStream", "PartnerDefaultStreamCreate", "PartnerDefaultStreamUpdate", "PartnerDeviceHeartbeatBody", "PartnerHeartbeatCommand", "PartnerHeartbeatData", "PartnerHeartbeatMeasurementMetadata", "PartnerHeartbeatQueryData", "PartnerHeartbeatQueryResponse", "PartnerHeartbeatRequest", "PartnerHeartbeatResponse", "PartnerHeartbeatTelemetry", "PartnerLBarContent", "PartnerLBarDisplayPreferences", "PartnerLBarSettings", "PartnerSafeHeartbeatTelemetry", "PartnerSelfPromoAd", "PartnerSelfPromoCreate", "PartnerSelfPromoPlacement", "PartnerStats", "PayoutResponse", "PlaygroundResult", "PlaygroundValidationError", "ProgrammaticSettingsInput", "ProgrammaticSettingsResponse", "RequestMetadataResponse", "RolePermissions", "SDKConfig", "ScreenAnalyticsResponse", "SsdpDeviceInfo", "TeamInviteResponse", "TeamMember", "Transaction", "Webhook", "WebhookDelivery", "WebhookEvent", "WifiEnvironmentSnapshot", "WifiScanResult"],
-  operations: ["listPartnerSelfPromoAds", "createPartnerSelfPromoAd", "listPartnerSelfPromoPlacements", "schedulePartnerSelfPromo", "createPartnerSelfPromoUpload", "disablePartnerSelfPromo", "registerAgent", "getAnalytics", "rotateApiKey", "getAudienceAnalytics", "exportAudienceData", "getAudienceHeatmap", "getLiveAudience", "getLookalikeScreens", "predictScreenAudience", "listAudienceSegments", "createAudienceSegment", "deleteAudienceSegment", "getAudienceSegment", "updateAudienceSegment", "matchAudienceSegment", "estimateSegmentReach", "generateSegmentVastTag", "getAudienceStats", "purchaseCredits", "createCreditCheckout", "setupBilling", "getUsageSummary", "getConnectDashboard", "getConnectEarningsChart", "getConnectScreenHealth", "listContentPresets", "getContentPreset", "getDashboard", "registerDevice", "deleteDevice", "getDevice", "updateDevice", "getAdsForDevice", "ackDeviceCommand", "getDeviceHeartbeat", "heartbeat", "recordProgrammaticEvent", "listDevices", "registerDevicesBatch", "batchUpdateDeviceOrientation", "getEarnings", "getEarningsBreakdown", "requestPayout", "getTransactions", "getActiveSSEConnections", "subscribeToEvents", "getFleetAnalytics", "pushFleetCommand", "getFleetOverview", "updateFleetSettings", "recordImpressionGet", "recordImpressionPost", "recordImpressionsBatch", "getPartnerInfo", "listIntentCategories", "getIntentCategory", "getIntentPricing", "getNetworkConfig", "patchNetworkConfig", "updateNetworkConfig", "recordAdComplete", "getPricing", "quickStart", "registerPartner", "generateSandboxEvent", "resetSandbox", "createSandboxScreen", "getSandboxStatus", "batchUpdateContentPreferences", "batchUpdateDisplaySettings", "batchUpdateProgrammaticSettings", "resolvePartnerScreen", "getScreenAnalytics", "applyContentPreset", "getAudienceMetrics", "getContentPreferences", "patchContentPreferences", "updateContentPreferences", "listPartnerDefaultStreams", "createPartnerDefaultStream", "createPartnerDefaultStreamImages", "reorderPartnerDefaultStreams", "createPartnerDefaultStreamUpload", "deletePartnerDefaultStream", "updatePartnerDefaultStream", "getScreenDemographics", "getDisplaySettings", "patchDisplaySettings", "updateDisplaySettings", "getPartnerLBarSettings", "updatePartnerLBarSettings", "updatePartnerLBarLiveUpdates", "getProgrammaticSettings", "patchProgrammaticSettings", "updateProgrammaticSettings", "createStripeConnectAccount", "getStripeLoginLink", "getStripeOnboardingLink", "requestStripePayout", "getStripePayoutHistory", "getStripeAccountStatus", "handleStripeWebhook", "listTeamMembers", "acceptInvitation", "inviteTeamMember", "getInvitationByToken", "resendInvitation", "removeTeamMember", "changeTeamMemberRole", "getTrackingPublicKey", "recordTrackingBatch", "upgradeToPartner", "getUsageSummary__get__usage", "getUsageDashboard", "getRateLimitStatus", "queryChangelog", "playgroundDryRun", "getRequestMetadata", "getVastConfig", "getVenueIntelligence", "listWebhooks", "createWebhook", "deleteWebhook", "updateWebhook", "getWebhookDeliveries", "testWebhook"]
+  schemaCount: 71,
+  operationCount: 175,
+  schemas: ["Ad", "AdSettings", "AudienceAnalyticsResponse", "AudienceAttentionPrediction", "AudienceExportResponse", "AudienceLoyaltyFeaturesRow", "AudienceMetricsResponse", "AudienceSegment", "AudienceSocialAttention", "BatchResult", "BleScanResultData", "ChangelogEntry", "ChangelogResponse", "ContentPreferencesInput", "ContentPreferencesResponse", "ContentPreset", "DashboardResponse", "DataExportSummaryResponse", "DemographicsResponse", "Device", "DeviceCapabilityPayload", "DeviceSummary", "DisplaySettingsInput", "DisplaySettingsResponse", "EarningsBreakdownResponse", "EarningsResponse", "Error", "HeaderBiddingSettings", "HttpProbeResult", "MdnsNetworkDevice", "Pagination", "Partner", "PartnerAdDeliveryProfile", "PartnerDefaultStream", "PartnerDefaultStreamCreate", "PartnerDefaultStreamUpdate", "PartnerDeviceHeartbeatBody", "PartnerHeartbeatCommand", "PartnerHeartbeatData", "PartnerHeartbeatMeasurementMetadata", "PartnerHeartbeatQueryData", "PartnerHeartbeatQueryResponse", "PartnerHeartbeatRequest", "PartnerHeartbeatResponse", "PartnerHeartbeatTelemetry", "PartnerLBarContent", "PartnerLBarDisplayPreferences", "PartnerLBarSettings", "PartnerSafeHeartbeatTelemetry", "PartnerSelfPromoAd", "PartnerSelfPromoCreate", "PartnerSelfPromoPlacement", "PartnerStats", "PayoutResponse", "PlaygroundResult", "PlaygroundValidationError", "ProgrammaticSettingsInput", "ProgrammaticSettingsResponse", "RequestMetadataResponse", "RolePermissions", "SDKConfig", "ScreenAnalyticsResponse", "SsdpDeviceInfo", "TeamInviteResponse", "TeamMember", "Transaction", "Webhook", "WebhookDelivery", "WebhookEvent", "WifiEnvironmentSnapshot", "WifiScanResult"],
+  operations: ["listPartnerSelfPromoAds", "createPartnerSelfPromoAd", "listPartnerSelfPromoPlacements", "schedulePartnerSelfPromo", "createPartnerSelfPromoUpload", "disableSelfPromoAd", "registerAgent", "getAnalytics", "getAudienceContinuity", "getAudienceProfile", "getBleSummary", "getContentPerformance", "searchCreativeCatalog", "getCreativeScenes", "getCrossScreenFlow", "getPartnerAnalyticsDashboard", "getDeviceSuiteSignature", "exportPartnerAnalytics", "exportPartnerAdsByDay", "getFleetHourly", "getHaloFunnel", "getLoyaltyClock", "getNetworkSummary", "getNetworkTrend", "getProximitySummary", "getRevenueAttentionCorrelation", "getSceneFeed", "getSceneIntelligence", "rotateApiKey", "getAudienceAnalytics", "exportAudienceData", "getAudienceHeatmap", "getLiveAudience", "getLookalikeScreens", "predictScreenAudience", "getResolvedHouseholdReach", "listAudienceSegments", "createAudienceSegment", "deleteAudienceSegment", "getAudienceSegment", "updateAudienceSegment", "matchAudienceSegment", "estimateSegmentReach", "generateSegmentVastTag", "getAudienceStats", "cancelBillingSubscription", "purchaseCredits", "createCreditCheckout", "listBillingPlans", "setupBilling", "createBillingSubscription", "getBillingSubscription", "getBillingUsage", "getUsageSummary", "stripeWebhookCallback", "getConnectDashboard", "getConnectEarningsChart", "getConnectScreenHealth", "listContentPresets", "getContentPreset", "getDashboard", "exportProximityGraphEdges", "getDataExportSummary", "exportDataset", "getGeohashAudiencePanel", "registerDevice", "deleteDevice", "getDevice", "updateDevice", "getAdsForDevice", "ackDeviceCommand", "getDeviceHeartbeat", "heartbeat", "recordProgrammaticEvent", "listDevices", "registerDevicesBatch", "batchUpdateDeviceOrientation", "partnerDocsBrowser", "getEarnings", "getEarningsBreakdown", "requestPayout", "getTransactions", "getActiveSSEConnections", "subscribeToEvents", "getFleetAnalytics", "pushFleetCommand", "getFleetOverview", "updateFleetSettings", "recordImpressionGet", "recordImpressionPost", "recordImpressionsBatch", "getPartnerInfo", "listIntentCategories", "getIntentCategory", "getIntentPricing", "getMeasurementMethodology", "getNetworkConfig", "patchNetworkConfig", "updateNetworkConfig", "getNetworkTrends", "partnerPing", "partnerPingAuth", "getPricing", "quickStart", "registerPartner", "generateSandboxEvent", "resetSandbox", "createSandboxScreen", "getSandboxStatus", "getScreenAudienceSegments", "batchUpdateContentPreferences", "batchUpdateDisplaySettings", "batchUpdateProgrammaticSettings", "resolvePartnerScreen", "getScreenAnalytics", "getPartnerScreenAtmosphere", "getPartnerScreenIntelligence", "getPartnerScreenTasteProfile", "getPartnerScreenTraffic", "getPartnerScreenVAS", "applyContentPreset", "getAudienceMetrics", "getContentPreferences", "patchContentPreferences", "updateContentPreferences", "listPartnerDefaultStreams", "createPartnerDefaultStream", "createPartnerDefaultStreamImages", "reorderPartnerDefaultStreams", "createPartnerDefaultStreamUpload", "deletePartnerDefaultStream", "updatePartnerDefaultStream", "getScreenDemographics", "getDisplaySettings", "patchDisplaySettings", "updateDisplaySettings", "getPartnerLBarSettings", "updatePartnerLBarSettings", "updatePartnerLBarLiveUpdates", "getProgrammaticSettings", "patchProgrammaticSettings", "updateProgrammaticSettings", "createStripeConnectAccount", "getStripeLoginLink", "getStripeOnboardingLink", "requestStripePayout", "getStripePayoutHistory", "getStripeAccountStatus", "handleStripeWebhook", "listTeamMembers", "acceptInvitation", "inviteTeamMember", "getInvitationByToken", "resendInvitation", "removeTeamMember", "changeTeamMemberRole", "getTrackingPublicKey", "recordTrackingBatch", "getUsageSummary__get__usage", "getUsageDashboard", "getRateLimitStatus", "queryChangelog", "playgroundDryRun", "getRequestMetadata", "getVastConfig", "getVenuesNearby", "getVenueAtmosphere", "getVenueTraffic", "getVenueIntelligence", "listWebhooks", "createWebhook", "deleteWebhook", "updateWebhook", "getWebhookDeliveries", "testWebhook"]
 };
 
-export { AnalyticsClient, AudienceClient, BillingClient, DataClient, DevicesClient, EarningsClient, ErrorsClient, FleetClient, ImpressionsClient, ScreensClient, TrillboardsClient, TrillboardsError, VERSION, Webhooks, WebhooksClient, constructEvent, generatedTypes };
+export { AnalyticsClient, AudienceClient, BillingClient, DataClient, DevicesClient, EarningsClient, ErrorsClient, FleetClient, ImpressionsClient, ScreensClient, TrillboardsClient, TrillboardsError, VERSION, Webhooks, WebhooksClient, constructEvent, constructEventLegacy, generatedTypes, parseSignatureHeader, retryWithBackoff };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map