@trillboards/api-client 3.1.15 → 3.2.1

package/README.md

@@ -8,7 +8,7 @@ Official TypeScript SDK for the Trillboards DOOH Partner API.
 npm install @trillboards/api-client
 ```
 
-Requires Node.js 18+ (uses native `fetch` and `crypto`). Zero runtime dependencies.
+Requires Node.js 18+. REST uses native `fetch`; media buying uses the official MCP client and streaming uses its shared SSE parser. Keep buying credentials in your server application.
 
 ## Quick Start
 
@@ -41,9 +41,80 @@ const { data: earnings } = await client.earnings.get({ period: 'month' });
 | `client.webhooks` | `list`, `create`, `update`, `delete`, `test` |
 | `client.fleet` | `pushCommand`, `listCommands` |
 | `client.audience` | `getLive`, `getHeatmap`, `getStats` |
-| `client.data` | `getVenueIntelligence`, `getUsage` |
+| `client.data` | `getVenueIntelligence`, `getUsage`, `listScreens`, `getHistory`, `getAudience`, `query`, `stream` |
 | `client.errors` | `list`, `get` |
-| `client.billing` | `get`, `getStripeStatus`, `requestPayout` |
+| `client.billing` | `setup`, `createCreditCheckout`, `purchaseCredits`, `getUsageSummary`, `get`, `getStripeStatus`, `requestPayout` |
+| `client.mediaBuys` | `getProducts`, `discoverInventory`, `listAccounts`, `syncAccounts`, `create`, `list`, `update`, `syncCreatives`, `getDelivery`, `close` |
+| `client.creativeExperiments` | `create`, `get`, `configureBrand`, `generate`, `importCreative`, `review`, `registerVariants`, `updatePolicy`, `getRewards`, `stop` |
+
+## Fund and run a creative feedback loop
+
+Use the [Creative AI Feedback Loop](https://api.trillboards.com/docs/guides/integrations/creative-feedback) for complete buying, creative review, serving and correction-aware reward examples. The same partner key works with REST and native MCP buying tools.
+
+Create a credit checkout with a stable key for this exact purchase, then open the returned Stripe URL:
+
+```typescript
+const checkout = await client.billing.createCreditCheckout(
+  { tier: 'tier_500' },
+  { idempotencyKey: 'my-first-credit-checkout-v1' },
+);
+console.log(checkout.checkout_url);
+```
+
+After completing payment, read the committed balance:
+
+```typescript
+const balance = await client.billing.getUsageSummary();
+console.log(balance.credit_balance_cents, balance.credit_reserved_cents);
+```
+
+Balances and metered amounts retain their exact decimal strings. A saved payment method alone does not fund delivery. Media uses its accepted quote; API usage uses the published API tariff.
+
+Direct `purchaseCredits` can return `requires_action: true` with a `client_secret`. Complete that payment's Stripe authentication, then read the committed balance; retain its `operation_id` and stable key. The SDK returns these fields unchanged. Stripe Checkout handles authentication in the returned browser flow.
+
+Discover your account and the live product catalog before creating a buy:
+
+```typescript
+try {
+  const accounts = await client.mediaBuys.listAccounts();
+  const products = await client.mediaBuys.getProducts({
+    brief: 'Transit screens for a creative attention test',
+    pagination: { max_results: 10 },
+  });
+  console.log(accounts.accounts, products.products, products.pagination);
+} finally {
+  await client.mediaBuys.close();
+}
+```
+
+`client.mediaBuys.create` takes the native AdCP request, including the account, flight, product/pricing-option identifiers, budget and stable `idempotency_key`. `list` accepts `media_buy_ids` and pagination; `update` accepts the native revision. Preserve `media_buy_id` and `packages[].package_id` for `creativeExperiments.create`. The MCP task's `status` describes task execution; the returned media-buy lifecycle, funding and moderation describe delivery readiness. Always release the MCP connection with `mediaBuys.close()` when finished.
+
+## Historical and live data
+
+The Data API resources require the scopes declared by their endpoints: `read:live`, `read:historical` or `stream:live`. Screen-list pagination is returned unchanged as `has_more` and `next_offset`. Bounded history reads preserve unmeasured values as `null`.
+
+```typescript
+const history = await client.data.getHistory('YOUR_SCREEN_ID', {
+  since: '2026-10-01T00:00:00Z',
+  until: '2026-10-02T00:00:00Z',
+  limit: 100,
+});
+console.log(history.metrics);
+
+const controller = new AbortController();
+try {
+  for await (const event of client.data.stream({}, { signal: controller.signal })) {
+    console.log(event.event, event.data);
+    if (event.event === 'audience') break;
+  }
+} finally {
+  controller.abort();
+}
+```
+
+The stream forwards `connected`, `audience` and in-band `error` events. Breaking iteration or aborting closes the connection. It is a live tail: reconnect explicitly and use bounded history reads to recover historical data. Creative reward corrections use the guide's canonical-key/revision scan protocol.
+
+MCP tool failures throw `McpToolError` with the exact `tool` and original `result`, including structured error codes and receipts. Protocol/HTTP errors from the official MCP transport remain intact. REST failures use `TrillboardsError`.
 
 ### Content fit
 

package/dist/chunk-JLSS2URG.mjs

@@ -0,0 +1,18 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/generated/index.ts
+var generatedTypes = {
+  schemaCount: 191,
+  operationCount: 237,
+  schemas: ["Ad", "AdSettings", "AdvertisingIdentity", "AnalyticsData", "AudienceAnalyticsResponse", "AudienceAttentionPrediction", "AudienceData", "AudienceExportResponse", "AudienceLoyaltyFeaturesRow", "AudienceMetricsResponse", "AudienceSegment", "AudienceSocialAttention", "BatchResult", "BillingInfo", "BleScanResultData", "CanonicalError", "ChangelogEntry", "ChangelogResponse", "CompletedImpressions", "ContentFitSettings", "ContentPreferencesInput", "ContentPreferencesResponse", "ContentPreset", "CreatePartnerSensingRouteRequest", "CreativeClassification", "CreativeRewardsReadyEvent", "DashboardResponse", "DataApi_AggregateResponse", "DataApi_Error", "DataApi_ErrorCode", "DataApi_ExampleHealthcheckResponse", "DataApi_FeedbackRewardQuery", "DataApi_LookalikeResponse", "DataApi_QueryDslBody", "DataApi_QueryDslResponse", "DataApi_QueryFilter", "DataApi_QueryOrderBy", "DataApi_ScreenAudienceResponse", "DataApi_ScreenHistoryResponse", "DataApi_ScreensListResponse", "DataApi_SemanticSearchResponse", "DataApi_StatsResponse", "DataApi_StreamResponse", "DataApi_UsageResponse", "DataExportSummaryResponse", "DemandPartners", "DemographicsResponse", "Device", "DeviceAuthRefusal", "DeviceCapabilityPayload", "DeviceSummary", "DisplaySettingsInput", "DisplaySettingsResponse", "EarnerScreens", "EarningsBreakdownResponse", "EarningsData", "EarningsResponse", "EarningsSources", "Error", "ErrorCode", "ErrorCodeResponse", "ErrorEntry", "ErrorEnvelope", "ErrorListItem", "ErrorListResponse", "ErrorType", "ExtendedIdentity", "FeedbackBrand", "FeedbackBrandRequest", "FeedbackBrandResponse", "FeedbackCreateRequest", "FeedbackCreativeReview", "FeedbackExperiment", "FeedbackExperimentDetail", "FeedbackExperimentDetailResponse", "FeedbackExperimentResponse", "FeedbackGenerateRequest", "FeedbackGenerateResponse", "FeedbackGeneratedCreative", "FeedbackImportRequest", "FeedbackPolicyRequest", "FeedbackRecoveredCreative", "FeedbackRegisterVariantsRequest", "FeedbackReviewRequest", "FeedbackReviewResponse", "FeedbackRewardQuery", "FeedbackRewardRow", "FeedbackRewards", "FeedbackRewardsResponse", "FeedbackStopRequest", "FeedbackVariant", "FleetCommand", "FleetCommandEvent", "HeaderBiddingSettings", "HttpProbeResult", "HybridError", "Impression", "LegacyCodedError", "LegacyError", "Mcp_create_media_buy_Args", "Mcp_discover_inventory_Args", "Mcp_get_media_buy_delivery_Args", "Mcp_get_media_buys_Args", "Mcp_get_products_Args", "Mcp_list_accounts_Args", "Mcp_sync_accounts_Args", "Mcp_sync_creatives_Args", "Mcp_update_media_buy_Args", "MdnsNetworkDevice", "MeasurementMethodology", "OpenrtbRevenueScreenHourly", "Pagination", "Partner", "PartnerAdDeliveryProfile", "PartnerCreativeWarnings", "PartnerDefaultStream", "PartnerDefaultStreamCreate", "PartnerDefaultStreamUpdate", "PartnerDeviceBatchRegistrationInput", "PartnerDeviceHeartbeatBody", "PartnerDevicePlay", "PartnerDeviceRegistrationInput", "PartnerHeartbeatCommand", "PartnerHeartbeatData", "PartnerHeartbeatMeasurementMetadata", "PartnerHeartbeatQueryData", "PartnerHeartbeatQueryResponse", "PartnerHeartbeatRequest", "PartnerHeartbeatResponse", "PartnerHeartbeatTelemetry", "PartnerInteraction", "PartnerLBarContent", "PartnerLBarDisplayPreferences", "PartnerLBarSettings", "PartnerLocationCapability", "PartnerLocationRail", "PartnerMonetizationRequirements", "PartnerNetworkConfig", "PartnerNetworkConfigUpdate", "PartnerPlay", "PartnerReconciliationReports", "PartnerRegistrationDisplaySettings", "PartnerRequirement", "PartnerSafeHeartbeatTelemetry", "PartnerSelfPromoAd", "PartnerSelfPromoCreate", "PartnerSelfPromoPlacement", "PartnerStats", "PartnerTripState", "PartnerVariants", "PartnerZoneCpmDaily", "PayoutResponse", "PlaygroundResult", "PlaygroundValidationError", "ProgrammaticSettingsInput", "ProgrammaticSettingsResponse", "RequestMetadataResponse", "ResolvedContentPolicy", "ResolvedSensingConfig", "RolePermissions", "SDKConfig", "Screen", "ScreenAnalyticsResponse", "ScreenGroup", "ScreenGroupContentPolicy", "ScreenGroupContentPolicyInput", "ScreenGroupEvent", "ScreenGroupSensingConfig", "ScreenGroupSensingConfigInput", "SensingPerformanceMode", "SensingRoute", "SensingRouteAction", "SensingRouteCondition", "SensingRouteReviewTimingMode", "SensingRouteReviewWaitSeconds", "SensingRouteScreenFocusRegion", "SensingSettingsResponse", "SensingThresholdCrossedEvent", "SsdpDeviceInfo", "TeamInviteResponse", "TeamMember", "Transaction", "TrillboardsError", "UpdatePartnerSensingRouteRequest", "VastWaterfall", "VastWaterfallSource", "Webhook", "WebhookDelivery", "WebhookEvent", "WifiEnvironmentSnapshot", "WifiScanResult"],
+  operations: ["queryChangelog", "dataApiAggregate", "dataApiLookalikeScreens", "dataApiQueryDsl", "dataApiListScreens", "dataApiScreenAudienceLive", "dataApiScreenAudienceHistory", "dataApiSemanticSearch", "dataApiStats", "dataApiStream", "dataApiUsage", "listErrorCodes", "getErrorCode", "exampleHealthcheck", "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", "getBillingUsageSummary", "stripeWebhookCallback", "getConnectDashboard", "getConnectEarningsChart", "getConnectScreenHealth", "listContentPresets", "getContentPreset", "createCreativeFeedbackExperiment", "getCreativeFeedbackExperiment", "configureCreativeFeedbackBrand", "generateCreativeFeedbackCreative", "importCreativeFeedbackCreative", "reviewCreativeFeedbackCreative", "updateCreativeFeedbackPolicy", "getCreativeFeedbackRewards", "stopCreativeFeedbackExperiment", "registerCreativeFeedbackVariants", "submitPartnerCreative", "getPartnerCreative", "getDashboard", "exportProximityGraphEdges", "getDataExportSummary", "exportDataset", "getGeohashAudiencePanel", "getOutcomeAttribution", "registerDevice", "deleteDevice", "getDevice", "updateDevice", "getAdsForDevice", "ackDeviceCommand", "getDeviceHeartbeat", "heartbeat", "recordPartnerDeviceInteraction", "recordPartnerDevicePlay", "recordProgrammaticEvent", "recordPartnerDeviceTripState", "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", "getMeasurementMethodologyJson", "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", "getUsageDashboard", "getRateLimitStatus", "getVastConfig", "getVenuesNearby", "getVenueAtmosphere", "getVenueTraffic", "getVenueIntelligence", "listWebhooks", "createWebhook", "deleteWebhook", "updateWebhook", "getWebhookDeliveries", "testWebhook", "playgroundDryRun", "getRequestMetadata"]
+};
+
+export { __require, generatedTypes };
+//# sourceMappingURL=chunk-JLSS2URG.mjs.map
+//# sourceMappingURL=chunk-JLSS2URG.mjs.map