@nautical-commerce/graphql-schema 3.11.0 → 3.12.0

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."""
@@ -6140,6 +6145,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."""
@@ -11150,6 +11184,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!]!
 
@@ -20730,6 +20769,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 +20935,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.0",
   "description": "Traide API GraphQL Schema",
   "main": "./nautical/schema.graphql",
   "scripts": {