Class: Portage::Ucp::Adapter Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/portage/ucp/adapter.rb

Overview

This class is abstract.

Subclass and override the methods for the capabilities you support. Unoverridden methods leave that capability out of the manifest.

Direct Known Subclasses

ReferenceAdapter

Instance Method Summary collapse

Instance Method Details

#cancel_cart(cart_id:, idempotency_key:) ⇒ Portage::Ucp::Cart

Returns:



33
 
# File 'lib/portage/ucp/adapter.rb', line 33

def cancel_cart(cart_id:, idempotency_key:) = not_implemented

#cancel_checkout(checkout_id:, idempotency_key:) ⇒ Portage::Ucp::Checkout

Returns:



72
 
# File 'lib/portage/ucp/adapter.rb', line 72

def cancel_checkout(checkout_id:, idempotency_key:) = not_implemented

#cancel_order(order_id:, idempotency_key:, reason: nil) ⇒ Portage::Ucp::Order

Cancels a placed order. reason is an optional human-readable note, not a closed enum — the platform-specific enum mapping (if any) is an adapter concern.

Returns:



81
82
83
84
85
86
87
 
# File 'lib/portage/ucp/adapter.rb', line 81

def cancel_order(order_id:, idempotency_key:, reason: nil) = not_implemented
# Requests a return for one or more order line items. `line_items` is an
# array of request-shaped hashes (`{id:, quantity:}`, unsigned) — same
# request/response asymmetry as `create_cart`'s `line_items:`. A return
# is a request the merchant still has to process; it shows up as a
# `pending` `Portage::Ucp::Adjustment` until they do.
# @return [Portage::Ucp::Order]

#complete_checkout(checkout_id:, payment_token:, idempotency_key:) ⇒ Portage::Ucp::Checkout

Re-checks stock at the point of committing money, since search_catalog/ get_product (dev.ucp.shopping.catalog) don't promise live inventory and nothing else re-checks between browsing and buying. An adapter whose platform rejects completion because a line item is out of stock or otherwise unavailable should raise Portage::Ucp::OutOfStockError rather than a generic/platform error, so callers can distinguish a stale-stock failure from e.g. a declined payment.

Parameters:

  • payment_token (String) —

    single-use token from a UCP payment handler / AP2 exchange — NEVER a raw PAN.

Returns:

Raises:



70
71
 
# File 'lib/portage/ucp/adapter.rb', line 70

def complete_checkout(checkout_id:, payment_token:, idempotency_key:) = not_implemented
# @return [Portage::Ucp::Checkout]

#create_cart(line_items:, idempotency_key:, discount_codes: nil) ⇒ Portage::Ucp::Cart

discount_codes: is the dev.ucp.shopping.discount extension — nil (the default) means the request didn't touch discounts at all; an adapter that doesn't override #discount_codes_supported? never sees anything but nil here (see below). Full-replacement like line_items: once codes are involved, [] clears them, same as UCP's own discounts_object semantics.

Returns:



29
30
 
# File 'lib/portage/ucp/adapter.rb', line 29

def create_cart(line_items:, idempotency_key:, discount_codes: nil) = not_implemented
# @return [Portage::Ucp::Cart]

#create_checkout(line_items:, idempotency_key:, discount_codes: nil, fulfillment: nil) ⇒ Portage::Ucp::Checkout

--- Checkout (dev.ucp.shopping.checkout) --- discount_codes: carries the same dev.ucp.shopping.discount semantics as create_cart/update_cart above. fulfillment: is the dev.ucp.shopping.fulfillment extension — nil (the default) means the request didn't touch fulfillment at all; an adapter that doesn't override #fulfillment_supported? never sees anything but nil here (see below). On create it carries the agent's desired methods (type + line_item_ids per shipping/pickup group — Portage::Ucp::FulfillmentMethod#id/#destinations/#groups are omitted since the merchant generates those); on update it carries the agent's selected_destination_id/selected_option_id choices against the methods/groups the merchant already returned.

Returns:



48
49
 
# File 'lib/portage/ucp/adapter.rb', line 48

def create_checkout(line_items:, idempotency_key:, discount_codes: nil, fulfillment: nil) = not_implemented
# @return [Portage::Ucp::Checkout]

#discount_codes_supported? ⇒ Boolean

--- Discount (dev.ucp.shopping.discount) --- Extends Cart/Checkout with the discount_codes: param above rather than adding actions of its own — Capability::DISCOUNT advertises off this predicate instead of an overridden action method, since there's no dedicated method for #advertised_for? to detect an override on.

Returns:

  • (Boolean) 


99
 
# File 'lib/portage/ucp/adapter.rb', line 99

def discount_codes_supported? = false

#fulfillment_supported? ⇒ Boolean

--- Fulfillment (dev.ucp.shopping.fulfillment) --- Extends Checkout with the fulfillment: param above rather than adding actions of its own — Capability::FULFILLMENT advertises off this predicate instead of an overridden action method, same rationale as #discount_codes_supported? above.

Returns:

  • (Boolean) 


107
 
# File 'lib/portage/ucp/adapter.rb', line 107

def fulfillment_supported? = false

#get_cart(cart_id:) ⇒ Portage::Ucp::Cart

--- Cart (dev.ucp.shopping.cart) --- Full-replacement semantics, matching UCP's real cart methods: create/ update take the complete desired line_items list, not a single item. line_items: is an array of request-shaped hashes (e.g. {product_id:, quantity:}) — the adapter looks up product data and builds the response's Item/Total/LineItem itself.

Returns:



21
22
23
24
25
26
27
28
 
# File 'lib/portage/ucp/adapter.rb', line 21

def get_cart(cart_id:) = not_implemented
# `discount_codes:` is the dev.ucp.shopping.discount extension — nil
# (the default) means the request didn't touch discounts at all; an
# adapter that doesn't override #discount_codes_supported? never sees
# anything but nil here (see below). Full-replacement like line_items:
# once codes are involved, [] clears them, same as UCP's own
# discounts_object semantics.
# @return [Portage::Ucp::Cart]

#get_checkout(checkout_id:) ⇒ Portage::Ucp::Checkout

Returns:



50
 
# File 'lib/portage/ucp/adapter.rb', line 50

def get_checkout(checkout_id:) = not_implemented

#get_order(order_id:) ⇒ Portage::Ucp::Order?

--- Order (dev.ucp.shopping.order) ---

Returns:



76
77
78
79
80
 
# File 'lib/portage/ucp/adapter.rb', line 76

def get_order(order_id:) = not_implemented
# Cancels a placed order. `reason` is an optional human-readable note,
# not a closed enum — the platform-specific enum mapping (if any) is an
# adapter concern.
# @return [Portage::Ucp::Order]

#get_product(product_id:) ⇒ Portage::Ucp::ProductDetail?

nil when the product isn't found, same not-found posture as get_cart/get_checkout/get_order.

Returns:



12
 
# File 'lib/portage/ucp/adapter.rb', line 12

def get_product(product_id:) = not_implemented

#link_identity(oauth_token:) ⇒ Portage::Ucp::Identity

--- Identity Linking (dev.ucp.shopping.identity, OAuth 2.0) ---

Returns:



111
 
# File 'lib/portage/ucp/adapter.rb', line 111

def link_identity(oauth_token:) = not_implemented

#refund_order(order_id:, line_items:, idempotency_key:, reason: nil) ⇒ Portage::Ucp::Order

Refunds one or more order line items.

Returns:



91
 
# File 'lib/portage/ucp/adapter.rb', line 91

def refund_order(order_id:, line_items:, idempotency_key:, reason: nil) = not_implemented

#request_return(order_id:, line_items:, idempotency_key:, reason: nil) ⇒ Portage::Ucp::Order

Requests a return for one or more order line items. line_items is an array of request-shaped hashes ({id:, quantity:}, unsigned) — same request/response asymmetry as create_cart's line_items:. A return is a request the merchant still has to process; it shows up as a pending Portage::Ucp::Adjustment until they do.

Returns:



88
89
90
 
# File 'lib/portage/ucp/adapter.rb', line 88

def request_return(order_id:, line_items:, idempotency_key:, reason: nil) = not_implemented
# Refunds one or more order line items.
# @return [Portage::Ucp::Order]

#search_catalog(query:, limit:) ⇒ Portage::Ucp::CatalogSearchResult

--- Catalog (dev.ucp.shopping.catalog) ---

Returns:



8
9
10
11
 
# File 'lib/portage/ucp/adapter.rb', line 8

def search_catalog(query:, limit:) = not_implemented
# nil when the product isn't found, same not-found posture as
# get_cart/get_checkout/get_order.
# @return [Portage::Ucp::ProductDetail, nil]

#update_cart(cart_id:, line_items:, idempotency_key:, discount_codes: nil) ⇒ Portage::Ucp::Cart

Returns:



31
32
 
# File 'lib/portage/ucp/adapter.rb', line 31

def update_cart(cart_id:, line_items:, idempotency_key:, discount_codes: nil) = not_implemented
# @return [Portage::Ucp::Cart]

#update_checkout(checkout_id:, line_items:, idempotency_key:, discount_codes: nil, fulfillment: nil) ⇒ Portage::Ucp::Checkout

Full-replacement, same as update_cart — line_items is required on checkout update per the real spec.

Returns:



55
56
57
 
# File 'lib/portage/ucp/adapter.rb', line 55

def update_checkout(checkout_id:, line_items:, idempotency_key:, discount_codes: nil, fulfillment: nil)
  not_implemented
end