@nautical-commerce/graphql-schema 4.6.0 → 4.8.0

package/nautical/schema.graphql

@@ -1515,7 +1515,9 @@ type Attribute implements Node & ObjectWithMetadata {
   """The input type to use for entering attribute values in the dashboard."""
   inputType: AttributeInputTypeEnum!
 
-  """The values available for this attribute"""
+  """
+  ALL values defined for this attribute — the full catalogue of options it can take, NOT the values assigned to any particular product or variant. For the values assigned to a specific object, use the `values` field on SelectedAttribute (a sibling of `attribute`, one level up). Narrowed to a subset when `search` or `first` is supplied. Returns an empty list unless `inputType` is DROPDOWN or MULTISELECT — the other input types carry a unique value per object rather than a shared catalogue.
+  """
   values(search: String = null, first: Int = null): [AttributeValue!]!
 
   """Seller who created this attribute, if any"""
@@ -6445,6 +6447,134 @@ input EmailTemplateUpdateInput {
   isCustom: Boolean = null
 }
 
+"""
+A customer's durable claim on something they bought, held separately from the artifacts that deliver it. A download link may expire or be re-issued without changing what the customer owns.
+"""
+type Entitlement implements Node {
+  """The Globally Unique ID of this object"""
+  id: ID!
+
+  """Identity the claim is bound to. Present even for guest checkouts."""
+  customerEmail: String!
+
+  """Units covered by this claim."""
+  quantity: Int!
+
+  """Product name as recorded at purchase — survives catalog changes."""
+  productName: String!
+
+  """Variant name at purchase."""
+  variantName: String!
+
+  """SKU at purchase."""
+  productSku: String!
+
+  """When the claim was granted."""
+  grantedAt: DateTime
+
+  """When the claim lapses, if ever."""
+  expiresAt: DateTime
+
+  """When the claim was withdrawn."""
+  revokedAt: DateTime
+
+  """Row creation time."""
+  createdAt: DateTime!
+
+  """Row last-modified time."""
+  updatedAt: DateTime!
+
+  """Lifecycle state of the claim."""
+  status: EntitlementStatus!
+
+  """How this was fulfilled, snapshotted at grant time."""
+  kind: FulfillmentKind!
+
+  """Why the claim was withdrawn, if it was."""
+  revokedReason: EntitlementRevokedReason
+
+  """
+  Whether redemption is permitted right now. Combines status with the expiry clock, since nothing sweeps lapsed rows.
+  """
+  isUsable: Boolean!
+
+  """The variant this claim covers, if it still exists."""
+  variant: ProductVariant
+
+  """Uses of this entitlement, most recent first."""
+  redemptions: [RedemptionEvent!]!
+
+  """Download credentials issued against this entitlement."""
+  contentUrls: [DigitalContentUrl!]!
+}
+
+"""A connection to a list of items."""
+type EntitlementCountableConnection {
+  """Pagination data for this connection"""
+  pageInfo: PageInfo!
+
+  """Contains the nodes in this connection"""
+  edges: [EntitlementCountableEdge!]!
+
+  """Total quantity of existing nodes."""
+  totalCount: Int!
+}
+
+"""An edge in a connection."""
+type EntitlementCountableEdge {
+  """A cursor for use in pagination"""
+  cursor: String!
+
+  """The item at the end of the edge"""
+  node: Entitlement!
+}
+
+"""Represents errors from entitlement operations."""
+type EntitlementError {
+  field: String
+
+  """The error message."""
+  message: String!
+
+  """The error code."""
+  code: EntitlementErrorCode!
+}
+
+"""An enumeration of possible error codes for entitlement operations."""
+enum EntitlementErrorCode {
+  GRAPHQL_ERROR
+  INTERNAL_ERROR
+  INVALID
+  NOT_FOUND
+}
+
+"""Payload for entitlementRevoke."""
+type EntitlementRevoke {
+  entitlement: Entitlement
+  entitlementErrors: [EntitlementError!]!
+}
+
+"""Why an entitlement was withdrawn. Drives downstream trust policy."""
+enum EntitlementRevokedReason {
+  REFUND
+  CHARGEBACK
+  FRAUD
+  OPERATOR
+  SELLER
+}
+
+"""
+Lifecycle of a customer's claim. States rather than booleans: 'revoked because refunded' and 'expired because the term ended' are different facts, and only ACTIVE permits redemption.
+"""
+enum EntitlementStatus {
+  PENDING
+  ACTIVE
+  SUSPENDED
+  EXPIRED
+  REVOKED
+  TRANSFERRED
+}
+
 """Represents a generic event in the audit log."""
 type Event {
   """The unique identifier across all event tables."""
@@ -8206,6 +8336,7 @@ type MarketplaceConfiguration {
   automaticFulfillmentDigitalProducts: Boolean!
   defaultDigitalMaxDownloads: Int
   defaultDigitalUrlValidDays: Int
+  revokeEntitlementsOnRefund: Boolean!
   trackInventoryByDefault: Boolean!
   name: String!
   defaultMailSenderName: String!
@@ -9828,10 +9959,10 @@ type Mutation {
   """Clear all seller shipping methods."""
   checkoutSellerShippingMethodsClear(checkoutId: ID!): CheckoutSellerShippingMethodsClear!
 
-  """Add a promo code (voucher or gift card)."""
+  """Add a voucher code to the checkout."""
   checkoutAddPromoCode(checkoutId: ID!, promoCode: String!): CheckoutAddPromoCode!
 
-  """Remove a promo code."""
+  """Remove a voucher code from the checkout."""
   checkoutRemovePromoCode(checkoutId: ID!, promoCode: String!): CheckoutRemovePromoCode!
 
   """Add purchase order numbers."""
@@ -9846,6 +9977,11 @@ type Mutation {
   """Complete checkout and create order."""
   checkoutComplete(checkoutId: ID!, storeSource: Boolean = false, poNumber: String = null, userOverride: ID = null, redirectUrl: String = null, paymentData: JSONString = null): CheckoutComplete!
 
+  """
+  Withdraw a customer's entitlement, invalidating any download links issued against it. Requires MANAGE_MARKETPLACE.
+  """
+  entitlementRevoke(id: ID!, reason: EntitlementRevokedReason! = OPERATOR): EntitlementRevoke!
+
   """Create a new payout synchronously."""
   payoutCreate(input: PayoutCreateInput!): PayoutCreate! @deprecated(reason: "This will be removed on July 15, 2025. Use payoutCreateAsync instead.")
 
@@ -17963,6 +18099,23 @@ type Query {
     last: Int = null
   ): RefundCountableConnection!
 
+  """
+  List entitlements. Requires MANAGE_ORDERS. Marketplace operators see every entitlement; a seller sees only claims against their own goods.
+  """
+  entitlements(
+    """Returns the items in the list that come before the specified cursor."""
+    before: String = null
+
+    """Returns the items in the list that come after the specified cursor."""
+    after: String = null
+
+    """Returns the first n items from the list."""
+    first: Int = null
+
+    """Returns the items in the list that come after the specified cursor."""
+    last: Int = null
+  ): EntitlementCountableConnection!
+
   """Look up a payout by ID. Requires MANAGE_PAYOUTS permission."""
   payout(id: ID!): Payout
 
@@ -18647,6 +18800,36 @@ enum RecipientTypeEnum {
   STAFF_MEMBER_MARKETPLACE_OR_SELLER @deprecated(reason: "Use STAFF_MEMBER_MARKETPLACE or STAFF_MEMBER_SELLER instead. This value will be deprecated on September 30, 2025")
 }
 
+"""
+A single use of an entitlement — a download now, a scan or activation later.
+"""
+type RedemptionEvent implements Node {
+  """The Globally Unique ID of this object"""
+  id: ID!
+
+  """When the redemption happened."""
+  occurredAt: DateTime!
+
+  """What kind of use this was."""
+  eventType: RedemptionEventType!
+
+  """
+  Key that made this redemption idempotent, when the producer supplied one. Downloads have none — every download is a distinct use.
+  """
+  idempotencyKey: String
+}
+
+"""
+A use of an entitlement. Only DOWNLOAD is produced in v1; the remaining values are reserved for the fulfillment kinds whose stacks have not shipped.
+"""
+enum RedemptionEventType {
+  DOWNLOAD
+  ACTIVATION
+  REVEAL
+  SCAN
+  CHECK_IN
+}
+
 """
 Represents a refund scoped to a nautical order, seller order, or order line.
 """
@@ -19669,10 +19852,14 @@ type SalesVelocityReport {
 
 """Represents a selected attribute with its values"""
 type SelectedAttribute {
-  """The attribute definition"""
+  """
+  The attribute definition. Its `values` field lists every value the attribute CAN take — for the values actually assigned here, use the `values` field alongside this one, not the one nested inside it.
+  """
   attribute: Attribute!
 
-  """Values of the attribute"""
+  """
+  The values assigned to THIS object — this product, variant, or custom-field owner. Usually the field you want. Contrast `attribute.values`, which is the attribute's full catalogue of possible values and is identical for every object sharing it.
+  """
   values: [AttributeValue!]!
 
   """
@@ -22709,6 +22896,23 @@ type User implements Node & ObjectWithMetadata {
     last: Int = null
   ): WishlistCountableConnection!
 
+  """
+  The customer's library — everything they own, including items whose download links have expired. Owner-scoped: only ever the requesting user's own entitlements.
+  """
+  entitlements(
+    """Returns the items in the list that come before the specified cursor."""
+    before: String = null
+
+    """Returns the items in the list that come after the specified cursor."""
+    after: String = null
+
+    """Returns the first n items from the list."""
+    first: Int = null
+
+    """Returns the items in the list that come after the specified cursor."""
+    last: Int = null
+  ): EntitlementCountableConnection!
+
   """List of documents associated with the user."""
   documents: [Document!]!
 
@@ -22982,6 +23186,7 @@ type VendorPayout implements Node & ObjectWithMetadata {
   gateway: String!
   included: Boolean!
   statusMessage: String
+  externalBatchId: String!
 
   """Adjustment amount."""
   adjustmentAmount: Float! @deprecated(reason: "This will be removed on August 6, 2025. Use the adjustment field instead.")
@@ -24195,6 +24400,10 @@ enum WebhookEventTypeEnum {
   COLLECTION_DELETED
   COLLECTION_UPDATED
   CUSTOMER_CREATED
+  DIGITAL_CONTENT_URL_CREATED
+  DIGITAL_CONTENT_URL_REVOKED
+  ENTITLEMENT_GRANTED
+  ENTITLEMENT_REVOKED
   CUSTOMER_UPDATED
   CUSTOMER_DELETED
   FULFILLMENT_CREATED

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nautical-commerce/graphql-schema",
-  "version": "4.6.0",
+  "version": "4.8.0",
   "description": "Traide API GraphQL Schema",
   "main": "./nautical/schema.graphql",
   "scripts": {