type: object
description: |
    A media entitlement — entitles a Bigscreen account to consume a specific media
    product. Mirrors `Schemas.Entitlement` (api/src/Schemas.ts). Created when a
    purchase, IAP, coupon redemption, or admin grant succeeds; transitions through
    a status state machine (`IDLE` → `ACTIVATED` → expired) and may carry session
    history.
required: [id, bigscreenAccountId, mediaProductId, bigMediaId, entitlementClass, status]
properties:
    id: { type: string }
    createdAt: { type: string, format: date-time }
    bigscreenAccountId:
        type: string
        description: Owner — the customer the entitlement belongs to.
    ip:
        type: string
        description: Customer IP captured at order time.
    receiptId:
        type: string
        description: Internal receipt id minted at purchase confirmation.
    receiptSnapshot:
        type: object
        additionalProperties: true
        description: Snapshot of the receipt at the time of purchase (auditing).
    mediaProductId:
        type: string
        description: Internal media product id. Immutable.
    bigMediaId:
        type: string
        description: Public media product id. Immutable.
    productSnapshot:
        type: object
        additionalProperties: true
        description: Snapshot of the product at purchase time.
    entitlementClass:
        type: string
        description: |
            Governs what happens when first used. Common values include
            `TWO_DAY_RENTAL`, `OWNERSHIP`, `FREE`, `PROMOTIONAL`. See `EntitlementClass`.
    status:
        type: string
        description: |
            State-machine position. `IDLE` (not yet activated), `ACTIVATED`,
            `EXPIRED`, `REFUNDED`, etc.
    activationTimestamp:
        type: [string, "null"]
        format: date-time
        description: When the entitlement was first activated. Null while `IDLE`. Set once.
    expirationTimestamp:
        type: [string, "null"]
        format: date-time
        description: When the entitlement expires. Set when activated for time-limited classes.
    sessions:
        type: array
        items:
            type: object
            additionalProperties: true
            description: Per-session record (device id, started at, ended at, etc.).
    maxAllowedSessions:
        type: integer
        description: -1 indicates unlimited.
    deviceHistory:
        type: array
        items:
            type: object
            additionalProperties: true
        description: Devices that have used this entitlement; empty if never used.
    checksum:
        type: string
        description: MD5 over `bigscreenAccountId` + `receiptId` + media. Internal integrity check.
example:
    id: "ent_01HZB12345ABC678DEF90GHJKM"
    createdAt: "2026-04-22T10:14:00.000Z"
    bigscreenAccountId: "acct_01HXJ4Q12345"
    ip: "203.0.113.10"
    receiptId: "rcpt_01HZB67890XYZ123"
    mediaProductId: "01HXKV8QRSTU9VWXYZABCDEFGH"
    bigMediaId: "bbb-2008"
    entitlementClass: "TWO_DAY_RENTAL"
    status: "ACTIVATED"
    activationTimestamp: "2026-04-22T11:00:00.000Z"
    expirationTimestamp: "2026-04-24T11:00:00.000Z"
    sessions: []
    maxAllowedSessions: -1
    deviceHistory: []
    checksum: "a3b2c1d4e5f60718"
