@trillboards/api-client 0.4.1 → 1.1.0

package/dist/index.mjs

@@ -1,3 +1,5 @@
+import { __require } from './chunk-FJ7QMMH4.mjs';
+export { generatedTypes } from './chunk-FJ7QMMH4.mjs';
 import { createHmac, timingSafeEqual } from 'crypto';
 
 // src/error.ts
@@ -70,7 +72,7 @@ var TrillboardsError = class _TrillboardsError extends Error {
 };
 
 // src/version.ts
-var VERSION = "0.4.1";
+var VERSION = "1.1.0";
 
 // src/http.ts
 var PUBLIC_PATHS = ["/v1/errors", "/v1/changelog", "/api/discover", "/v1/health"];
@@ -353,7 +355,14 @@ var WebhooksClient = class {
   async list() {
     return this.http.get("/v1/partner/webhooks");
   }
-  /** Create a new webhook subscription. */
+  /**
+   * Create a new webhook subscription.
+   *
+   * The created `Webhook` carries its signing `secret` (`whsec_…`) — this is the
+   * ONLY time it is returned. Persist it securely and pass it to
+   * `Webhooks.constructEvent()` to verify the compound `X-Trillboards-Signature`
+   * header over the raw delivery body.
+   */
   async create(body) {
     return this.http.post("/v1/partner/webhooks", body);
   }
@@ -621,20 +630,174 @@ function constructEventLegacy(payload, signature, secret) {
   }
   return JSON.parse(payloadStr);
 }
+var ADCP_WEBHOOK_SIGNING_TAG = "adcp/webhook-signing/v1";
+var ADCP_WEBHOOK_COMPONENTS = [
+  "@method",
+  "@target-uri",
+  "@authority",
+  "content-type",
+  "content-digest"
+];
+var ADCP_MAX_WINDOW_SECONDS = 300;
+function splitDictionary(headerValue) {
+  const members = [];
+  let depth = 0;
+  let quoted = false;
+  let start = 0;
+  for (let i = 0; i < headerValue.length; i++) {
+    const ch = headerValue[i];
+    if (quoted) {
+      if (ch === "\\") i++;
+      else if (ch === '"') quoted = false;
+      continue;
+    }
+    if (ch === '"') quoted = true;
+    else if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    else if (ch === "," && depth === 0) {
+      members.push(headerValue.slice(start, i).trim());
+      start = i + 1;
+    }
+  }
+  members.push(headerValue.slice(start).trim());
+  return members.filter((member) => member.length > 0);
+}
+function dictionaryMember(headerValue, label) {
+  return splitDictionary(headerValue).find((member) => member.startsWith(`${label}=`));
+}
+var ADCP_SIGNATURE_LABEL = "sig1";
+function selectAdcpSignatureInput(signatureInput) {
+  const members = splitDictionary(signatureInput);
+  const named = members.find((member) => member.startsWith(`${ADCP_SIGNATURE_LABEL}=`));
+  if (named) return { label: ADCP_SIGNATURE_LABEL, member: named };
+  const tagged = members.find((member) => member.includes(`tag="${ADCP_WEBHOOK_SIGNING_TAG}"`));
+  if (tagged) return { label: tagged.slice(0, tagged.indexOf("=")), member: tagged };
+  throw authError(
+    `AdCP webhook has no "${ADCP_SIGNATURE_LABEL}" signature member and no member tagged "${ADCP_WEBHOOK_SIGNING_TAG}".`
+  );
+}
+function canonicalTargetUri(rawUrl) {
+  const parsed = new URL(rawUrl);
+  const beforeFragment = rawUrl.split("#", 1)[0];
+  const search = parsed.search || (beforeFragment.endsWith("?") ? "?" : "");
+  return `${parsed.protocol}//${parsed.host}${parsed.pathname}${search}`.replace(
+    /%([0-9a-fA-F]{2})/g,
+    (match, hex) => {
+      const code = parseInt(hex, 16);
+      const unreserved = code >= 65 && code <= 90 || code >= 97 && code <= 122 || code >= 48 && code <= 57 || code === 45 || code === 46 || code === 95 || code === 126;
+      return unreserved ? String.fromCharCode(code) : `%${hex.toUpperCase()}`;
+    }
+  );
+}
+function verifyAdcpWebhook(opts) {
+  const { createHash, createPublicKey, verify: cryptoVerify } = __require("crypto");
+  const signatureInput = getHeader(opts.headers, "Signature-Input");
+  const signature = getHeader(opts.headers, "Signature");
+  if (!signatureInput || !signature) {
+    throw authError("AdCP webhook is missing the Signature / Signature-Input header pair.");
+  }
+  const { label, member: inputMember } = selectAdcpSignatureInput(signatureInput);
+  const signatureMember = dictionaryMember(signature, label);
+  if (!signatureMember) {
+    throw authError(`AdCP webhook Signature has no "${label}" member to match Signature-Input.`);
+  }
+  const paramsStart = inputMember.indexOf("(");
+  const paramsEnd = inputMember.indexOf(")");
+  if (paramsStart < 0 || paramsEnd < 0) {
+    throw authError("AdCP webhook Signature-Input is malformed.");
+  }
+  const components = inputMember.slice(paramsStart + 1, paramsEnd).split(" ").map((component) => component.replace(/^"|"$/g, "")).filter((component) => component.length > 0);
+  const readParam = (name) => {
+    const match = new RegExp(`;${name}=("?)([^";]+)\\1`).exec(inputMember);
+    return match ? match[2] : void 0;
+  };
+  const created = Number(readParam("created"));
+  const expires = Number(readParam("expires"));
+  const nonce = readParam("nonce");
+  const keyid = readParam("keyid");
+  const alg = readParam("alg");
+  const tag = readParam("tag");
+  if (!nonce || !keyid || !alg || !Number.isFinite(created) || !Number.isFinite(expires)) {
+    throw authError("AdCP webhook signature is missing a required parameter.");
+  }
+  if (tag !== ADCP_WEBHOOK_SIGNING_TAG) {
+    throw authError(`AdCP webhook signature has tag "${tag}", expected "${ADCP_WEBHOOK_SIGNING_TAG}".`);
+  }
+  if (alg !== "ed25519") {
+    throw authError(`AdCP webhook signature algorithm "${alg}" is not allowed.`);
+  }
+  for (const required of ADCP_WEBHOOK_COMPONENTS) {
+    if (!components.includes(required)) {
+      throw authError(`AdCP webhook signature does not cover "${required}".`);
+    }
+  }
+  if (expires <= created || expires - created > ADCP_MAX_WINDOW_SECONDS) {
+    throw authError("AdCP webhook signature window is invalid.");
+  }
+  const now = opts.nowSec ?? Math.floor(Date.now() / 1e3);
+  if (now > expires) {
+    throw authError("AdCP webhook signature has expired. Possible replay attack.");
+  }
+  const jwk = opts.keys.find((key) => key.kid === keyid);
+  if (!jwk) {
+    throw authError(`AdCP webhook signed with unknown key "${keyid}". Refresh the JWKS.`);
+  }
+  if (jwk.key_ops && !jwk.key_ops.includes("verify")) {
+    throw authError(`AdCP webhook key "${keyid}" is not a verification key.`);
+  }
+  if (jwk.adcp_use && jwk.adcp_use !== "request-signing" && jwk.adcp_use !== "webhook-signing") {
+    throw authError(`AdCP webhook key "${keyid}" has adcp_use "${jwk.adcp_use}".`);
+  }
+  const payloadBuf = typeof opts.payload === "string" ? Buffer.from(opts.payload, "utf8") : opts.payload;
+  const contentDigest = getHeader(opts.headers, "Content-Digest");
+  const expectedDigest = `sha-256=:${createHash("sha256").update(payloadBuf).digest("base64")}:`;
+  if (!contentDigest || contentDigest !== expectedDigest) {
+    throw authError("AdCP webhook Content-Digest does not match the body.");
+  }
+  const method = (opts.method ?? "POST").toUpperCase();
+  const target = new URL(opts.url);
+  const baseLines = components.map((component) => {
+    switch (component) {
+      case "@method":
+        return `"@method": ${method}`;
+      case "@target-uri":
+        return `"@target-uri": ${canonicalTargetUri(opts.url)}`;
+      case "@authority":
+        return `"@authority": ${target.host.toLowerCase()}`;
+      default: {
+        const value = getHeader(opts.headers, component);
+        if (value === void 0) {
+          throw authError(`AdCP webhook covers "${component}" but the header is absent.`);
+        }
+        return `"${component}": ${value.trim()}`;
+      }
+    }
+  });
+  baseLines.push(`"@signature-params": ${inputMember.slice(label.length + 1)}`);
+  const signatureBytes = Buffer.from(
+    signatureMember.slice(label.length + 1).replace(/^:|:$/g, ""),
+    "base64url"
+  );
+  const publicKey = createPublicKey({ key: jwk, format: "jwk" });
+  if (!cryptoVerify(null, Buffer.from(baseLines.join("\n"), "utf8"), publicKey, signatureBytes)) {
+    throw authError(
+      "AdCP webhook signature verification failed. The delivery may have been tampered with."
+    );
+  }
+  return {
+    event: JSON.parse(payloadBuf.toString("utf8")),
+    keyid,
+    nonce,
+    expires
+  };
+}
 var Webhooks = {
   constructEvent,
   constructEventLegacy,
-  parseSignatureHeader
-};
-
-// src/generated/index.ts
-var generatedTypes = {
-  schemaCount: 99,
-  operationCount: 210,
-  schemas: ["Ad", "AdSettings", "AudienceAnalyticsResponse", "AudienceAttentionPrediction", "AudienceExportResponse", "AudienceLoyaltyFeaturesRow", "AudienceMetricsResponse", "AudienceSegment", "AudienceSocialAttention", "BatchResult", "BleScanResultData", "ChangelogEntry", "ChangelogResponse", "ContentFitSettings", "ContentPreferencesInput", "ContentPreferencesResponse", "ContentPreset", "CreatePartnerSensingRouteRequest", "CreativeClassification", "DashboardResponse", "DataExportSummaryResponse", "DemographicsResponse", "Device", "DeviceCapabilityPayload", "DeviceSummary", "DisplaySettingsInput", "DisplaySettingsResponse", "EarningsBreakdownResponse", "EarningsResponse", "Error", "FleetCommand", "FleetCommandEvent", "HeaderBiddingSettings", "HttpProbeResult", "MdnsNetworkDevice", "Pagination", "Partner", "PartnerAdDeliveryProfile", "PartnerDefaultStream", "PartnerDefaultStreamCreate", "PartnerDefaultStreamUpdate", "PartnerDeviceHeartbeatBody", "PartnerHeartbeatCommand", "PartnerHeartbeatData", "PartnerHeartbeatMeasurementMetadata", "PartnerHeartbeatQueryData", "PartnerHeartbeatQueryResponse", "PartnerHeartbeatRequest", "PartnerHeartbeatResponse", "PartnerHeartbeatTelemetry", "PartnerLBarContent", "PartnerLBarDisplayPreferences", "PartnerLBarSettings", "PartnerMonetizationRequirements", "PartnerNetworkConfig", "PartnerNetworkConfigUpdate", "PartnerPlay", "PartnerRegistrationDisplaySettings", "PartnerRequirement", "PartnerSafeHeartbeatTelemetry", "PartnerSelfPromoAd", "PartnerSelfPromoCreate", "PartnerSelfPromoPlacement", "PartnerStats", "PayoutResponse", "PlaygroundResult", "PlaygroundValidationError", "ProgrammaticSettingsInput", "ProgrammaticSettingsResponse", "RequestMetadataResponse", "ResolvedContentPolicy", "ResolvedSensingConfig", "RolePermissions", "SDKConfig", "ScreenAnalyticsResponse", "ScreenGroup", "ScreenGroupContentPolicy", "ScreenGroupContentPolicyInput", "ScreenGroupEvent", "ScreenGroupSensingConfig", "ScreenGroupSensingConfigInput", "SensingPerformanceMode", "SensingRoute", "SensingRouteAction", "SensingRouteCondition", "SensingSettingsResponse", "SensingThresholdCrossedEvent", "SsdpDeviceInfo", "TeamInviteResponse", "TeamMember", "Transaction", "UpdatePartnerSensingRouteRequest", "VastWaterfall", "VastWaterfallSource", "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", "submitPartnerCreative", "getPartnerCreative", "getDashboard", "exportProximityGraphEdges", "getDataExportSummary", "exportDataset", "getGeohashAudiencePanel", "getOutcomeAttribution", "registerDevice", "deleteDevice", "getDevice", "updateDevice", "getAdsForDevice", "ackDeviceCommand", "getDeviceHeartbeat", "heartbeat", "recordProgrammaticEvent", "listDevices", "registerDeviceV2", "registerDevicesBatch", "batchUpdateDeviceOrientation", "reconcileDevices", "partnerDocsBrowser", "getEarnings", "getEarningsBreakdown", "requestPayout", "getTransactions", "getActiveSSEConnections", "subscribeToEvents", "getFleetCommand", "getFleetAnalytics", "pushFleetCommand", "getFleetOverview", "updateFleetSettings", "recordImpressionGet", "recordImpressionPost", "recordImpressionsBatch", "getPartnerInfo", "listIntentCategories", "getIntentCategory", "getIntentPricing", "getMeasurementMethodology", "getNetworkConfig", "patchNetworkConfig", "updateNetworkConfig", "getNetworkTrends", "partnerPing", "partnerPingAuth", "recordPartnerPlay", "recordPartnerPlaysBatch", "getPricing", "recordProgrammaticEventLegacyAlias", "quickStart", "registerPartner", "generateSandboxEvent", "resetSandbox", "createSandboxScreen", "getSandboxStatus", "listScreenGroups", "createScreenGroup", "deleteScreenGroup", "getScreenGroup", "updateScreenGroup", "getScreenGroupAnalytics", "createScreenGroupCommand", "getScreenGroupContentPolicy", "updateScreenGroupContentPolicy", "removeScreenGroupMembers", "listScreenGroupMembers", "addScreenGroupMembers", "getScreenGroupSensingConfig", "updateScreenGroupSensingConfig", "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", "getResolvedContentPolicy", "getResolvedSensingConfig", "getScreenSensingChips", "interpretScreenSensingIntent", "deployScreenSensingProfile", "getScreenSensingSettings", "updateScreenSensingSettings", "listPartnerSensingRoutes", "createPartnerSensingRoute", "deletePartnerSensingRoute", "getPartnerSensingRoute", "updatePartnerSensingRoute", "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"]
+  parseSignatureHeader,
+  verifyAdcpWebhook
 };
 
-export { AnalyticsClient, AudienceClient, BillingClient, DataClient, DevicesClient, EarningsClient, ErrorsClient, FleetClient, ImpressionsClient, RoutesClient, ScreensClient, TrillboardsClient, TrillboardsError, VERSION, Webhooks, WebhooksClient, constructEvent, constructEventLegacy, generatedTypes, parseSignatureHeader, retryWithBackoff };
+export { ADCP_WEBHOOK_SIGNING_TAG, AnalyticsClient, AudienceClient, BillingClient, DataClient, DevicesClient, EarningsClient, ErrorsClient, FleetClient, ImpressionsClient, RoutesClient, ScreensClient, TrillboardsClient, TrillboardsError, VERSION, Webhooks, WebhooksClient, constructEvent, constructEventLegacy, parseSignatureHeader, retryWithBackoff, verifyAdcpWebhook };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map