@trillboards/api-client 0.1.2 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Trillboards, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -341,22 +341,26 @@ declare class EarningsClient {
 }
 
 /**
- * ErrorsClient — query the partner error log.
+ * ErrorsClient — access the public error catalog and query partner errors.
  *
- * Base path: /v1/partner
+ * list() hits /v1/errors (public, no auth required).
+ * get()  hits /v1/partner/usage (authenticated, partner-scoped).
  */
 
 declare class ErrorsClient {
     private readonly http;
     constructor(http: HttpClient);
-    /** List recent errors for this partner. */
+    /**
+     * List all known API error codes from the public error catalog.
+     * This endpoint does NOT require authentication.
+     */
     list(params?: {
         limit?: number;
         offset?: number;
         code?: string;
         type?: string;
     }): Promise<ListResponse<ErrorEntry>>;
-    /** Get a single error by request_id. */
+    /** Get a single error by request_id (requires authentication). */
     get(requestId: string): Promise<{
         success: boolean;
         data: ErrorEntry;
@@ -635,8 +639,391 @@ declare const Webhooks: {
  * SDK version constant. Sent in User-Agent and X-Trillboards-Client headers.
  * Keep in sync with package.json version.
  */
-declare const VERSION = "0.1.2";
+declare const VERSION = "0.1.3";
 
-declare const generatedTypes: {};
+type BleScanResultData = {
+    appleContinuitySubtype?: number | null;
+    deviceType?: number | null;
+    ibeaconMajor?: number | null;
+    ibeaconMinor?: number | null;
+    ibeaconUuid?: string | null;
+    manufacturerCompanyId?: number | null;
+    rawAddress: string;
+    rssi: number;
+    serviceUuids?: Array<string> | null;
+    stableManufacturerPayloadHex?: string | null;
+    txPowerDbm?: number | null;
+    [key: string]: unknown;
+};
+type DeviceCapabilityPayload = {
+    agentType?: string | null;
+    agentVersion?: string | null;
+    audienceSensing?: {
+        cameraAvailable?: boolean | null;
+        cameraCount?: number | null;
+        cameraHealth?: {
+            lastFailureClass?: string | null;
+            lastFailureMessage?: string | null;
+            lastFrameAtMs?: number | null;
+            retryCount?: number | null;
+            state?: string | null;
+            [key: string]: unknown;
+        } | null;
+        cameraType?: string | null;
+        microphoneAvailable?: boolean | null;
+        sensingMode?: string | null;
+        [key: string]: unknown;
+    } | null;
+    audioControl?: {
+        mute?: boolean | null;
+        volume?: boolean | null;
+        [key: string]: unknown;
+    } | null;
+    capabilitiesVersion?: number | null;
+    environmentSensors?: {
+        ambientLight?: boolean | null;
+        temperature?: boolean | null;
+        [key: string]: unknown;
+    } | null;
+    inputControl?: {
+        appSwitch?: boolean | null;
+        hdmi?: boolean | null;
+        [key: string]: unknown;
+    } | null;
+    isDeviceOwner?: boolean | null;
+    managementCapabilities?: {
+        clearCache?: boolean | null;
+        installApk?: boolean | null;
+        kioskMode?: boolean | null;
+        reboot?: boolean | null;
+        restart?: boolean | null;
+        screenshot?: boolean | null;
+        wipe?: boolean | null;
+        [key: string]: unknown;
+    } | null;
+    mlCapabilities?: {
+        availableRamMb?: number | null;
+        chipsetName?: string | null;
+        chipsetVendor?: string | null;
+        cpuAbi?: string | null;
+        densityDpi?: number | null;
+        gpuDelegateSupported?: boolean | null;
+        gpuName?: string | null;
+        hasNpu?: boolean | null;
+        maxVlmSizeMb?: number | null;
+        nnapiSupported?: boolean | null;
+        npuName?: string | null;
+        osApiLevel?: number | null;
+        recommendedModelTier?: string | null;
+        screenHeightPx?: number | null;
+        screenWidthPx?: number | null;
+        totalRamMb?: number | null;
+        [key: string]: unknown;
+    } | null;
+    powerControl?: {
+        cec?: boolean | null;
+        softBlackout?: boolean | null;
+        wol?: boolean | null;
+        [key: string]: unknown;
+    } | null;
+    wifiCsiSensing?: {
+        csiAvailable?: boolean | null;
+        csiHardwareType?: string | null;
+        csiNodeCount?: number | null;
+        [key: string]: unknown;
+    } | null;
+    [key: string]: unknown;
+};
+type HttpProbeResult = {
+    host: string;
+    port?: number | null;
+    server?: string | null;
+    [key: string]: unknown;
+};
+type MdnsNetworkDevice = {
+    host?: string | null;
+    instanceName: string;
+    mdnsModel?: string | null;
+    mdnsSoftwareVersion?: string | null;
+    mdnsVendor?: string | null;
+    port?: number | null;
+    serviceType: string;
+    [key: string]: unknown;
+};
+type PartnerAdDeliveryProfile = {
+    android_api_level?: number | null;
+    auto_recovery_enabled?: boolean;
+    ima_integration?: "android_native" | "html5_webview" | "disabled" | "unknown";
+    mode?: "ima_sdk" | "vast_fallback";
+    notes?: Array<string>;
+    reason?: string;
+    webview_chromium_major?: number | null;
+};
+/**
+ * Heartbeat payload from agent-core / agent-core-lite Android partner
+ * SDKs. Only includes fields verified populated in production
+ * `signal_observations` (last 30 days). Stub fields wired in Kotlin but
+ * never observed in CH are intentionally excluded; re-add only after
+ * telemetry confirms >1% population over 7 days.
+ *
+ */
+type PartnerDeviceHeartbeatBody = {
+    advertisingId?: string | null;
+    advertisingIdType?: "gaid" | "idfa" | null | null;
+    bleDeviceCount?: number;
+    capabilities?: DeviceCapabilityPayload;
+    discoveredNetworkDevices?: Array<MdnsNetworkDevice> | null;
+    fingerprint?: string;
+    gatewayIpHash?: string | null;
+    httpProbes?: Array<HttpProbeResult> | null;
+    limitAdTracking?: boolean | null;
+    metadata?: Record<string, unknown>;
+    /** Capped at 50 devices (RSSI-sorted, strongest first). */
+    nearbyBleDevices?: Array<BleScanResultData> | null;
+    nearbyWifiNetworks?: Array<WifiScanResult> | null;
+    networkDeviceCount?: number;
+    /** Heartbeat schema version (1=baseline, 2=nativeSensorSnapshot) */
+    schemaVersion?: number;
+    screenId?: string | null;
+    /** Per-source skip-reason counter map. Shape `{source: {reason: count}}`. */
+    skipReasonCounts?: Record<string, Record<string, number>>;
+    ssdpDevices?: Array<SsdpDeviceInfo> | null;
+    status?: string;
+    wifiBssidHash?: string | null;
+    wifiEnvironment?: WifiEnvironmentSnapshot;
+    wifiNetworkCount?: number;
+    wifiSsidHash?: string | null;
+    [key: string]: unknown;
+};
+type PartnerHeartbeatCommand = {
+    /** Command normalized for partner SDK compatibility. */
+    command?: string;
+    id?: string;
+    payload?: Record<string, unknown>;
+    queued_at?: string;
+};
+type PartnerHeartbeatData = {
+    ad_delivery_profile?: PartnerAdDeliveryProfile;
+    commands?: Array<PartnerHeartbeatCommand>;
+    last_seen_at?: string;
+    status?: "online" | "offline";
+};
+type PartnerHeartbeatMeasurementMetadata = {
+    ageSeconds?: number | null;
+    cachedAt?: string | null;
+    receivedAt?: string | null;
+    source?: "redis_twin" | "pg_fallback" | "unknown";
+    [key: string]: unknown;
+};
+type PartnerHeartbeatQueryData = {
+    adDeliveryProfile?: PartnerAdDeliveryProfile;
+    deviceId: string;
+    lastHeartbeatAt?: string | null;
+    measurementMetadata?: PartnerHeartbeatMeasurementMetadata;
+    stalenessSeconds?: number | null;
+    telemetry?: PartnerSafeHeartbeatTelemetry;
+    [key: string]: unknown;
+};
+type PartnerHeartbeatQueryResponse = {
+    data?: PartnerHeartbeatQueryData;
+    success?: boolean;
+};
+/**
+ * Optional heartbeat payload. Nested telemetry objects are preferred; legacy flat keys
+ * are still accepted for backward compatibility.
+ *
+ */
+type PartnerHeartbeatRequest = {
+    ad?: {
+        last_vast_request_at?: string;
+        last_vast_response_at?: string;
+        proof_of_play_enabled?: boolean;
+    };
+    agent_status?: string;
+    agent_version?: string;
+    android_api_level?: number;
+    brightness?: number;
+    desugaring_enabled?: boolean;
+    device?: {
+        android_api_level?: number;
+        make?: string;
+        model?: string;
+        os?: string;
+        osv?: string;
+        webview_chromium_major?: number;
+    };
+    ima_integration?: "android_native" | "html5_webview" | "disabled" | "unknown";
+    ima_sdk_version?: string;
+    ima_support_reason?: string;
+    ima_supported?: boolean;
+    input_source?: string;
+    last_ima_error_code?: number;
+    last_vast_error_code?: number;
+    last_vast_request_at?: string;
+    last_vast_response_at?: string;
+    /** Alternate namespace for telemetry keys (legacy support). */
+    metadata?: Record<string, unknown>;
+    muted?: boolean;
+    network?: {
+        bandwidthMbps?: number;
+        connectionType?: string;
+        downlinkMbps?: number;
+        effectiveType?: string;
+        latencyRtt?: number;
+        rtt?: number;
+        saveData?: boolean;
+    };
+    network_strength_dbm?: number;
+    power_state?: "on" | "standby" | "off" | "unknown";
+    proof_of_play_enabled?: boolean;
+    sdk?: {
+        android_api_level?: number;
+        desugaring_enabled?: boolean;
+        ima_integration?: "android_native" | "html5_webview" | "disabled" | "unknown";
+        ima_sdk_version?: string;
+        ima_supported?: boolean;
+        version?: string;
+        webview_chromium_major?: number;
+    };
+    sdk_version?: string;
+    telemetry?: PartnerHeartbeatTelemetry;
+    temperature_c?: number;
+    uptime_seconds?: number;
+    volume?: number;
+    webview_chromium_major?: number;
+};
+type PartnerHeartbeatResponse = {
+    data?: PartnerHeartbeatData;
+    success?: boolean;
+};
+type PartnerHeartbeatTelemetry = {
+    agentStatus?: string;
+    agentVersion?: string;
+    android_api_level?: number;
+    bandwidthMbps?: number;
+    brightness?: number;
+    connectionType?: string;
+    desugaring_enabled?: boolean;
+    downlinkMbps?: number;
+    ima_integration?: "android_native" | "html5_webview" | "disabled" | "unknown";
+    ima_sdk_version?: string;
+    ima_support_reason?: string;
+    ima_supported?: boolean;
+    inputSource?: string;
+    last_ima_error_code?: number;
+    last_vast_error_code?: number;
+    last_vast_request_at?: string;
+    last_vast_response_at?: string;
+    latencyRtt?: number;
+    make?: string;
+    model?: string;
+    muted?: boolean;
+    networkConnectionType?: string;
+    networkEffectiveType?: string;
+    networkStrengthDbm?: number;
+    os?: string;
+    osVersion?: string;
+    osv?: string;
+    powerState?: "on" | "standby" | "off" | "unknown";
+    proof_of_play_enabled?: boolean;
+    rtt?: number;
+    saveData?: boolean;
+    temperatureC?: number;
+    uptimeSeconds?: number;
+    volume?: number;
+    webview_chromium_major?: number;
+    [key: string]: unknown;
+};
+/**
+ * Partner-safe subset of device telemetry. Strips MDM compliance,
+ * Vertex embeddings, identity-correction internals, partner identifiers,
+ * and Mongo `_id` so partners only see what they need to decide
+ * whether a device is healthy enough to receive ads.
+ *
+ */
+type PartnerSafeHeartbeatTelemetry = {
+    agentStatus?: string | null;
+    agentVersion?: string | null;
+    bandwidthMbps?: number | null;
+    brightness?: number | null;
+    connectionType?: string | null;
+    consecutiveAdFailures?: number | null;
+    effectiveType?: string | null;
+    latencyRtt?: number | null;
+    make?: string | null;
+    model?: string | null;
+    muted?: boolean | null;
+    networkStrengthDbm?: number | null;
+    onlineStatus?: "online" | "offline" | "standby" | "unknown" | null;
+    os?: string | null;
+    osv?: string | null;
+    powerState?: string | null;
+    temperatureC?: number | null;
+    ua?: string | null;
+    uptimeSeconds?: number | null;
+    visibilityState?: string | null;
+    volume?: number | null;
+    [key: string]: unknown;
+};
+type SsdpDeviceInfo = {
+    friendlyName?: string | null;
+    location: string;
+    manufacturer?: string | null;
+    modelName?: string | null;
+    server?: string | null;
+    st: string;
+    udn?: string | null;
+    [key: string]: unknown;
+};
+type WifiEnvironmentSnapshot = {
+    channelCongestionRatio?: number | null;
+    connectedChannelWidthMhz?: number | null;
+    connectedFrequencyMhz?: number | null;
+    connectedLinkSpeedMbps?: number | null;
+    connectedSignalDbm?: number | null;
+    frequencyBand?: string | null;
+    medianSignalDbm?: number | null;
+    networkCount?: number | null;
+    rssiVariance?: number | null;
+    scanTimestampMs?: number | null;
+    signalSpreadDbm?: number | null;
+    uniqueBssidCount?: number | null;
+    [key: string]: unknown;
+} | null;
+type WifiScanResult = {
+    channelWidthMhz?: number | null;
+    frequencyMhz: number;
+    rawBssid: string;
+    signalStrengthDbm: number;
+    [key: string]: unknown;
+};
+/**
+ * Read live device heartbeat state
+ * GET /device/{deviceId}/heartbeat
+ */
+interface getDeviceHeartbeatOperation {
+    readonly path: "/device/{deviceId}/heartbeat";
+    readonly method: "GET";
+    request: never;
+    response: PartnerHeartbeatQueryResponse;
+}
+/**
+ * Device heartbeat
+ * POST /device/{deviceId}/heartbeat
+ */
+interface heartbeatOperation {
+    readonly path: "/device/{deviceId}/heartbeat";
+    readonly method: "POST";
+    request: PartnerHeartbeatRequest | PartnerDeviceHeartbeatBody;
+    response: PartnerHeartbeatResponse;
+}
+declare const generatedTypes: {
+    readonly schemaCount: 67;
+    readonly operationCount: 132;
+    readonly schemas: readonly ["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"];
+    readonly operations: readonly ["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"];
+};
+type GeneratedSchemaName = (typeof generatedTypes.schemas)[number];
+type GeneratedOperationName = (typeof generatedTypes.operations)[number];
 
-export { AnalyticsClient, type AnalyticsData, type ApiErrorType, AudienceClient, type AudienceData, BillingClient, type BillingInfo, type ClientOptions, DataClient, type Device, DevicesClient, EarningsClient, type EarningsData, type ErrorDetail, type ErrorEntry, type ErrorResponseBody, ErrorsClient, FleetClient, type FleetCommand, type Impression, ImpressionsClient, type ListResponse, type RequestOptions, type Screen, ScreensClient, TrillboardsClient, TrillboardsError, type TrillboardsErrorOptions, VERSION, type Webhook, type WebhookEvent, Webhooks, WebhooksClient, constructEvent, generatedTypes };
+export { AnalyticsClient, type AnalyticsData, type ApiErrorType, AudienceClient, type AudienceData, BillingClient, type BillingInfo, type BleScanResultData, type ClientOptions, DataClient, type Device, type DeviceCapabilityPayload, DevicesClient, EarningsClient, type EarningsData, type ErrorDetail, type ErrorEntry, type ErrorResponseBody, ErrorsClient, FleetClient, type FleetCommand, type GeneratedOperationName, type GeneratedSchemaName, type HttpProbeResult, type Impression, ImpressionsClient, type ListResponse, type MdnsNetworkDevice, type PartnerAdDeliveryProfile, type PartnerDeviceHeartbeatBody, type PartnerHeartbeatMeasurementMetadata, type PartnerHeartbeatQueryData, type PartnerHeartbeatQueryResponse, type PartnerHeartbeatRequest, type PartnerHeartbeatResponse, type PartnerSafeHeartbeatTelemetry, type RequestOptions, type Screen, ScreensClient, type SsdpDeviceInfo, TrillboardsClient, TrillboardsError, type TrillboardsErrorOptions, VERSION, type Webhook, type WebhookEvent, Webhooks, WebhooksClient, type WifiEnvironmentSnapshot, type WifiScanResult, constructEvent, generatedTypes, type getDeviceHeartbeatOperation, type heartbeatOperation };