@nautical-commerce/graphql-schema 3.11.0 → 3.12.1

package/nautical/schema.graphql

@@ -395,7 +395,12 @@ type Agreement implements Node {
 
     """Returns the items in the list that come after the specified cursor."""
     last: Int = null
-  ): AgreementEventCountableConnection!
+  ): AgreementEventCountableConnection! @deprecated(reason: "Use `Agreement.timeline` instead. The `events` field only returns Agreement-level pghistory rows; `timeline` returns a unified feed across Agreement, AgreementCommission, AgreementFees, and AgreementSellers.")
+
+  """
+  Unified change-history feed for this agreement. Combines events from Agreement, AgreementCommission, AgreementFees, and AgreementSellers, projected into a normalized TimelineEntry shape. Ordered most-recent-first. Optional `kinds` argument filters the included sources server-side.
+  """
+  timeline(kinds: [TimelineEntryKind!] = null): [TimelineEntry!]!
 }
 
 """Result of agreement bulk delete mutation."""
@@ -2590,6 +2595,96 @@ type BulkStockError {
   index: Int
 }
 
+"""Result of the bundleCreate mutation."""
+type BundleCreate {
+  product: Product
+  productErrors: [ProductError!]!
+}
+
+"""Fields required to create a product bundle."""
+input BundleCreateInput {
+  """Bundle display name."""
+  name: String!
+
+  """URL slug. Auto-generated from name when omitted."""
+  slug: String = null
+
+  """
+  Seller that owns this bundle. Defaults to the caller's seller for non-MPO users. MPO must provide this field.
+  """
+  seller: ID = null
+
+  """Fixed bundle price (the customer-facing amount)."""
+  price: PositiveDecimal!
+
+  """Bundle currency. Defaults to the seller's default currency."""
+  currency: String = null
+
+  """SKU for the bundle's sellable variant."""
+  sku: String = null
+
+  """Whether the bundle is immediately published."""
+  isPublished: Boolean! = false
+
+  """
+  List of component variants composing the bundle. Must contain at least 2 components.
+  """
+  components: [BundleItemInput!]!
+}
+
+"""Result of the bundleDelete mutation."""
+type BundleDelete {
+  product: Product
+  productErrors: [ProductError!]!
+}
+
+"""
+A single component within a product bundle: how many of one ProductVariant are included in the bundle. SPEC-020 Feature 2.
+"""
+type BundleItem implements Node {
+  """The Globally Unique ID of this object"""
+  id: ID!
+
+  """How many units of this component are included per bundle."""
+  quantity: Int!
+
+  """Display order of this component within the bundle."""
+  sortOrder: Int
+
+  """The component variant this entry refers to."""
+  componentVariant: ProductVariant!
+}
+
+"""A single component slot within a bundle."""
+input BundleItemInput {
+  """Global ID of the ProductVariant included as a component."""
+  componentVariantId: ID!
+
+  """How many units of this component are included per bundle. Must be ≥ 1."""
+  quantity: Int! = 1
+
+  """Display order of this component within the bundle."""
+  sortOrder: Int = null
+}
+
+"""Result of the bundleUpdate mutation."""
+type BundleUpdate {
+  product: Product
+  productErrors: [ProductError!]!
+}
+
+"""Fields for updating a product bundle."""
+input BundleUpdateInput {
+  name: String = null
+  price: PositiveDecimal = null
+  isPublished: Boolean = null
+
+  """
+  Optional replacement set of components. When provided, replaces the current component set entirely (atomic). Omit to keep components unchanged.
+  """
+  components: [BundleItemInput!] = null
+}
+
 """CSV file metadata extracted during parsing."""
 type CSVMetadata {
   """Column headers from the CSV"""
@@ -6140,6 +6235,35 @@ enum FeeType {
   FIXED
 }
 
+type FieldChange {
+  """Raw Python field name, e.g. 'default_commission'."""
+  field: String!
+
+  """Humanized label, e.g. 'Default Commission'."""
+  fieldLabel: String!
+
+  """Previous value as JSON. Null for create events."""
+  fromValue: JSONString
+
+  """New value as JSON. Null for delete events."""
+  toValue: JSONString
+
+  """Semantic type hint for client-side formatting."""
+  valueType: FieldValueType!
+}
+
+enum FieldValueType {
+  PERCENTAGE
+  MONEY
+  STRING
+  DATE
+  DATETIME
+  ENUM
+  BOOLEAN
+  JSON
+  NUMBER
+}
+
 """Represents a file."""
 type File {
   """The URL of the file."""
@@ -8460,13 +8584,19 @@ type Mutation {
   """Publish pages."""
   pageBulkPublish(ids: [ID!]!, isPublished: Boolean!): PageBulkPublish!
 
-  """Creates a new policy."""
+  """
+  Creates a new policy. MPO staff with MANAGE_STOREFRONTS may create policies for any seller or marketplace-level (seller=null); seller users may create policies only for their own seller.
+  """
   policyCreate(input: PolicyInput!): PolicyCreate!
 
-  """Updates an existing policy."""
+  """
+  Updates an existing policy. Seller users may update only their own policies; MPO staff may update any policy. Reassigning ownership (changing seller) requires MANAGE_STOREFRONTS.
+  """
   policyUpdate(id: ID!, input: PolicyInput!): PolicyUpdate!
 
-  """Deletes a policy."""
+  """
+  Deletes a policy. Seller users may delete only their own policies; MPO staff may delete any policy.
+  """
   policyDelete(id: ID!): PolicyDelete!
 
   """Deletes policies."""
@@ -9236,6 +9366,17 @@ type Mutation {
   """Creates a download URL for digital content."""
   digitalContentUrlCreate(input: DigitalContentUrlCreateInput!): DigitalContentUrlCreate!
 
+  """
+  Create a product bundle. Builds a Product flagged is_bundle=True + its single sellable ProductVariant + BundleItem rows for each component, all in one transaction.
+  """
+  bundleCreate(input: BundleCreateInput!): BundleCreate!
+
+  """Update an existing bundle (name, price, components, is_published)."""
+  bundleUpdate(id: ID!, input: BundleUpdateInput!): BundleUpdate!
+
+  """Delete a bundle product. Cascades to its variant and BundleItems."""
+  bundleDelete(id: ID!): BundleDelete!
+
   """Register a new user account."""
   accountRegister(input: AccountRegisterInput!): AccountRegister!
 
@@ -11150,6 +11291,11 @@ type Order implements Node & ObjectWithMetadata {
     last: Int = null
   ): OrderAuditEventCountableConnection!
 
+  """
+  Unified change-history feed for this order. Combines pghistory events from Order (status/total/shipping changes), OrderLine (line additions/updates/removals), and Fulfillment (status, tracking) into a single TimelineEntry list ordered most-recent-first. Mirrors the Agreement timeline pattern. Optional `kinds` argument filters server-side.
+  """
+  timeline(kinds: [TimelineEntryKind!] = null): [TimelineEntry!]!
+
   """List of fees for this order"""
   fees: [OrderFee!]!
 
@@ -13364,6 +13510,11 @@ type Policy implements Node & ObjectWithMetadata {
 
   """The category of this policy"""
   category: PolicyCategory!
+
+  """
+  The seller that owns this policy, or null for marketplace-level policies.
+  """
+  seller: Seller
 }
 
 """Result of policy bulk delete mutation."""
@@ -13453,12 +13604,14 @@ enum PolicyErrorCode {
 }
 
 """
-Policy(id, publication_date, is_published, created_at, updated_at, content, content_html, tenant, seo_title, seo_description, category, slug, title)
+Policy(id, publication_date, is_published, created_at, updated_at, content, content_html, tenant, seo_title, seo_description, category, slug, title, seller)
 """
 input PolicyFilterInput {
   search: String
   isPublished: Boolean
   category: String
+  seller: String
+  marketplaceOnly: Boolean
   AND: PolicyFilterInput
   OR: PolicyFilterInput
   NOT: PolicyFilterInput
@@ -13484,6 +13637,11 @@ input PolicyInput {
 
   """Search engine optimization fields."""
   seo: SeoInput = null
+
+  """
+  Seller that owns this policy. If omitted, defaults to the calling seller user's own seller; MPO staff may omit it to create a marketplace-level policy.
+  """
+  seller: ID = null
 }
 
 """Fields available for sorting policies"""
@@ -13613,6 +13771,11 @@ type Product implements Node & ObjectWithMetadata {
   """Whether shipping is required"""
   isShippingRequired: Boolean!
 
+  """
+  Whether this product is a bundle. A bundle has exactly one sellable variant whose availability is derived from its BundleItem components (SPEC-020 Feature 2).
+  """
+  isBundle: Boolean!
+
   """Whether sellers can add variants"""
   allowSellerVariants: Boolean!
 
@@ -14116,6 +14279,11 @@ input ProductDimensionsInput {
   length: PositiveDecimal = null
   width: PositiveDecimal = null
   height: PositiveDecimal = null
+
+  """
+  Unit for length, width, and height. When omitted, the marketplace's configured default length unit is used.
+  """
+  unit: LengthUnitsStrEnum = null
 }
 
 """Represents errors from product operations."""
@@ -14200,7 +14368,7 @@ enum ProductFieldEnum {
 }
 
 """
-Product(id, publication_date, is_published, private_metadata, metadata, description, description_html, deleted_at, deleted_by_user, deleted_by_app, deletion_batch_uuid, external_id, external_source, external_inventory_id, tenant, seller, seo_title, seo_description, product_type, name, slug, search_vector, category, currency, minimal_variant_price_amount, updated_at, created_at, charge_taxes, weight, available_for_purchase, visible_in_listings, default_variant, cumulative_price_amount, override_price, override_currency, status, sub_status, is_price_override_allowed, is_shipping_required, is_digital, warnings, product_source, allow_seller_variants, minimal_variant_price, cumulative_price)
+Product(id, publication_date, is_published, private_metadata, metadata, description, description_html, deleted_at, deleted_by_user, deleted_by_app, deletion_batch_uuid, external_id, external_source, external_inventory_id, tenant, seller, seo_title, seo_description, product_type, name, slug, search_vector, category, currency, minimal_variant_price_amount, updated_at, created_at, charge_taxes, weight, available_for_purchase, visible_in_listings, default_variant, cumulative_price_amount, override_price, override_currency, status, sub_status, is_price_override_allowed, is_shipping_required, is_digital, is_bundle, warnings, product_source, allow_seller_variants, minimal_variant_price, cumulative_price)
 """
 input ProductFilterInput {
   isPublished: Boolean
@@ -15036,6 +15204,21 @@ type ProductVariant implements Node & ObjectWithMetadata {
   """Quantity of variant available for sale"""
   quantityAvailable(countryCode: CountryCode = null): Int!
 
+  """
+  Whether this variant belongs to a bundle product. Equivalent to `product.isBundle` — exposed here so clients can branch on the variant without an additional product lookup.
+  """
+  isBundle: Boolean!
+
+  """
+  If this variant is a bundle, the list of component variants and their quantities. Empty list for non-bundle variants.
+  """
+  bundleItems: [BundleItem!]!
+
+  """
+  Derived availability for a bundle variant — min over components of floor(component_available / bundle_item.quantity). Returns the standard quantity_available for non-bundle variants so clients can use this field uniformly.
+  """
+  bundleAvailableQuantity(countryCode: CountryCode = null): Int!
+
   """Total quantity ordered."""
   quantityOrdered: Int
 
@@ -16236,7 +16419,9 @@ type Query {
   """Look up a seller by ID, number (PK), or slug"""
   seller(id: ID = null, number: ID = null, taxId: String = null, slug: String = null): Seller
 
-  """List sellers (MPO only)"""
+  """
+  List sellers. Requires MANAGE_MARKETPLACE, except for the cross-sell discovery use case (filter.hasCrossSellProducts=true), which is open to any authenticated user so sellers can browse other sellers' cross-sell-enabled catalogs.
+  """
   sellers(
     filter: SellerFilterInput
     sortBy: SellerSortingInput = null
@@ -20730,6 +20915,92 @@ type TimeSeriesDataPoint {
   label: String
 }
 
+type TimelineActor {
+  type: TimelineActorType!
+
+  """
+  Display name for the actor (user email, app name, task name, or 'Anonymous').
+  """
+  label: String!
+
+  """Email when actor is a user."""
+  email: String
+
+  """
+  Global ID for the actor's settings page (user_id or app_id). The dashboard uses this to deep-link from the timeline row.
+  """
+  linkTargetId: String
+}
+
+enum TimelineActorType {
+  USER
+  APP
+  TASK
+  ANONYMOUS
+}
+
+type TimelineEntry {
+  """
+  Composite ID: '<kind>:<pgh_id>'. Stable per source event but not globally addressable via the Node interface.
+  """
+  id: ID!
+  timestamp: DateTime!
+  kind: TimelineEntryKind!
+  action: TimelineEntryAction!
+
+  """
+  Original pghistory label (e.g. 'commission_added'). Preserved alongside `action` for domain-specific UX.
+  """
+  rawLabel: String!
+
+  """
+  Server-formatted human-readable message, e.g. 'Granular commission for Seller "Acme" updated'. Pre-rendered to keep the frontend generic.
+  """
+  summary: String!
+  actor: TimelineActor!
+
+  """Child object affected. Null when the event IS the primary entity."""
+  target: TimelineTarget
+
+  """
+  Field-level diff. Empty for non-update events or when no fields changed.
+  """
+  changes: [FieldChange!]!
+
+  """Full snapshot at event time. Escape hatch for power users / debugging."""
+  rawSnapshot: JSONString!
+
+  """Full diff dict {field: [old, new]}. Null for create/delete events."""
+  rawDiff: JSONString
+}
+
+enum TimelineEntryAction {
+  CREATED
+  UPDATED
+  DELETED
+}
+
+enum TimelineEntryKind {
+  AGREEMENT
+  AGREEMENT_COMMISSION
+  AGREEMENT_FEE
+  AGREEMENT_SELLER
+  ORDER
+  ORDER_LINE
+  FULFILLMENT
+}
+
+type TimelineTarget {
+  """Lowercase model name, e.g. 'seller', 'product', 'category'."""
+  type: String!
+
+  """Human-readable identifier (name, title, etc)."""
+  label: String!
+
+  """Global ID for navigation. Null when no detail page exists."""
+  linkTargetId: String
+}
+
 """Result of token create mutation."""
 type TokenCreate {
   """JWT token for authentication."""
@@ -20810,15 +21081,15 @@ type Transaction implements Node {
   """Transaction token."""
   token: String!
 
-  """Transaction kind (auth, capture, void, refund)."""
-  kind: String!
-
   """Whether the transaction was successful."""
   isSuccess: Boolean!
 
   """Error message if transaction failed."""
   error: String
 
+  """The kind of the transaction."""
+  kind: TransactionKind!
+
   """The payment associated with this transaction."""
   payment: Payment!
 

package/package.json

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