model

type AckNoCallbackErr ¶ added in v1.7.0

type AckNoCallbackErr struct {
	// Status is ACK when the request was accepted but no callback will follow,
	// or NACK when the request was outright rejected.
	Status Status
	// Err explains why no callback will be sent. Required by the spec.
	Err *Error
}

AckNoCallbackErr is returned by a step when the receiver has authenticated and accepted the request but will not send an async callback — for example, no matching catalog, inventory unavailable, or provider closed. ONIX maps this to HTTP 202 Accepted using the v2 flat response shape. For protocol versions prior to 2.0.0 this error falls through to a 500 Internal Server Error.

func NewAckNoCallbackErr(status Status, err *Error) *AckNoCallbackErr

func (e *AckNoCallbackErr) BecknError() *Error

func (e *AckNoCallbackErr) Error() string

type BecknErrorer ¶ added in v1.8.1

type BecknErrorer interface {
	error
	BecknError() *Error
}

BecknErrorer is implemented by any error type that can produce its own *Error NACK representation. nackBecknError (core/module/handler/responsestep.go) dispatches on a short list of concrete types first (SchemaValidationErr, CodedErr, AckNoCallbackErr) for their HTTP status codes, then falls back to this interface for any other type — so a new error type can be wired into NACK dispatch by implementing BecknError() *Error alone, without core importing the plugin package that defines it. The fallback always answers 400; a type needing another status should return a *CodedErr instead.

type CodedErr ¶ added in v1.8.2

type CodedErr struct {
	// Code is the taxonomy value for this failure's specific cause, or ""
	// if unclassified, in which case BecknError() reports defaultCode.
	Code string
	// contains filtered or unexported fields
}

CodedErr wraps one cause with an optional taxonomy code and the HTTP status to NACK it with. It replaces BadReqErr, SignValidationErr and NotFoundErr, which stored the same fields and differed only in the status nackBecknError (core/module/handler/responsestep.go) picked for each by type switch. That status is now set at construction.

Use NewCodedErr, or NewBadReqErr, NewSignValidationErr and NewNotFoundErr for the 400, 401 and 404 cases and their message prefixes. Status, prefix and default code are unexported, so a usable value comes from a constructor.

SchemaValidationErr and AckNoCallbackErr stay separate. They differ in shape, not just status.

func NewBadReqErr(code string, err error) *CodedErr

func NewCodedErr(httpStatus int, code string, err error) *CodedErr

func NewNotFoundErr(code string, err error) *CodedErr

func NewSignValidationErr(code string, err error) *CodedErr

func WrapExtractContextErr(prefix string, becknErr *Error) *CodedErr

func (e *CodedErr) BecknError() *Error

func (e *CodedErr) Error() string

func (e *CodedErr) HTTPStatus() int

func (e *CodedErr) Unwrap() error

type ContextKey ¶

type ContextKey string

ContextKey is a custom type used as a key for storing and retrieving values in a context.

const (
	// ContextKeyTxnID is the context key used to store and retrieve the transaction ID in a request context.
	ContextKeyTxnID ContextKey = "transaction_id"

	// ContextKeyMsgID is the context key used to store and retrieve the message ID in a request context.
	ContextKeyMsgID ContextKey = "message_id"

	// ContextKeySubscriberID is the context key used to store and retrieve the subscriber ID in a request context.
	ContextKeySubscriberID ContextKey = "subscriber_id"

	// ContextKeyModuleID is the context key for storing and retrieving the model ID from a request context.
	ContextKeyModuleID ContextKey = "module_id"

	// ContextKeyParentID is the context key for  storing  and retrieving the parent ID from a request context
	ContextKeyParentID ContextKey = "parent_id"

	// ContextKeyRemoteID is the context key for the caller who is calling the bap/bpp
	ContextKeyRemoteID ContextKey = "remote_id"

	// ContextKeyProtocolVersion is the context key for the Beckn protocol version
	// extracted from context.version in the inbound request body.
	ContextKeyProtocolVersion ContextKey = "protocol_version"

	// ContextKeyNetworkID is the context key for the network identifier extracted from
	// context.network_id (or context.networkId) in the inbound request body.
	ContextKeyNetworkID ContextKey = "network_id"
)

func ParseContextKey(v string) (ContextKey, error)

func (k *ContextKey) UnmarshalYAML(unmarshal func(interface{}) error) error

type Error ¶

type Error struct {
	Code    string        `json:"code"`
	Message string        `json:"message"`
	Details *ErrorDetails `json:"details,omitempty"`
	// contains filtered or unexported fields
}

Error represents a standard error response.

func ExtractContext(body []byte) (req map[string]interface{}, reqContext map[string]interface{}, becknErr *Error)

func NewCodedError(code, message string) *Error

func NewCodedErrorWithCause(code, message, path string, cause error) *Error

func (e *Error) Error() string

func (e *Error) Unwrap() error

type ErrorDetails ¶ added in v1.8.1

type ErrorDetails struct {
	Path  string `json:"path,omitempty"`
	Cause *Error `json:"cause,omitempty"`
}

ErrorDetails carries optional structured context for an Error: a JSONPath to the failing field, and/or a chained root-cause Error from a downstream layer.

type Keyset ¶

type Keyset struct {
	SubscriberID   string
	UniqueKeyID    string // UniqueKeyID is the identifier for the key pair.
	SigningPrivate string // SigningPrivate is the private key used for signing operations.
	SigningPublic  string // SigningPublic is the public key corresponding to the signing private key.
	EncrPrivate    string // EncrPrivate is the private key used for encryption operations.
	EncrPublic     string // EncrPublic is the public key corresponding to the encryption private key.
}

Keyset represents a collection of cryptographic keys used for signing and encryption.

type ManifestDocument ¶ added in v1.6.0

type ManifestDocument struct {
	NetworkID    string    `json:"network_id,omitempty"`
	SubscriberID string    `json:"subscriber_id,omitempty"`
	ContentType  string    `json:"content_type,omitempty"`
	Content      []byte    `json:"content"`
	Digest       string    `json:"digest"`
	SourceURL    string    `json:"source_url"`
	SignatureURL string    `json:"signature_url"`
	Verified     bool      `json:"verified"`
	FetchedAt    time.Time `json:"fetched_at"`
}

ManifestDocument is the cached and returned verified manifest payload.

type ManifestMetadata ¶ added in v1.6.0

type ManifestMetadata struct {
	ManifestURL               string
	ManifestSignatureURL      string
	SigningPublicKeyLookupURL string
}

ManifestMetadata describes the three inputs needed to fetch and verify a manifest.

type Message ¶

type Message struct {
	// Status holds the acknowledgment status (ACK/NACK).
	Status Status `json:"status"`
	// MessageID echoes the context.messageId from the inbound request.
	MessageID string `json:"messageId,omitempty"`
	// Error holds error details when Status is NACK.
	Error *Error `json:"error,omitempty"`
}

Message represents the synchronous response message envelope (Beckn v2.0.0 LTS shape). The status and messageId are direct fields; the legacy "ack" wrapper is gone. For wire format: {"message":{"status":"ACK","messageId":"<uuid>"}}.

type NetworkManifest ¶ added in v1.6.0

type NetworkManifest struct {
	ManifestVersion string                    `yaml:"manifestVersion"`
	ManifestType    string                    `yaml:"manifestType"`
	NetworkID       string                    `yaml:"networkId"`
	ReleaseID       any                       `yaml:"releaseId"`
	Publisher       NetworkManifestPublisher  `yaml:"publisher"`
	Policies        *NetworkManifestPolicies  `yaml:"policies"`
	Governance      NetworkManifestGovernance `yaml:"governance"`
}

NetworkManifest is the typed YAML schema for a network-manifest document.

func ParseNetworkManifest(content []byte) (*NetworkManifest, error)

func (m *NetworkManifest) Validate(expectedNetworkID string, now time.Time) error

type NetworkManifestBundle ¶ added in v1.6.0

type NetworkManifestBundle struct {
	ID                        string `yaml:"id"`
	URL                       string `yaml:"url"`
	PolicyQueryPath           string `yaml:"policyQueryPath"`
	Signed                    bool   `yaml:"signed"`
	SigningPublicKeyLookupURL string `yaml:"signingPublicKeyLookupUrl"`
}

NetworkManifestBundle describes an OPA bundle policy artifact.

type NetworkManifestFile ¶ added in v1.6.0

type NetworkManifestFile struct {
	ID                        string `yaml:"id"`
	URL                       string `yaml:"url"`
	PolicyQueryPath           string `yaml:"policyQueryPath"`
	Signed                    bool   `yaml:"signed"`
	SignatureURL              string `yaml:"signatureUrl"`
	SigningPublicKeyLookupURL string `yaml:"signingPublicKeyLookupUrl"`
}

NetworkManifestFile describes a single Rego policy artifact.

type NetworkManifestGovernance ¶ added in v1.6.0

type NetworkManifestGovernance struct {
	EffectiveFrom  string `yaml:"effectiveFrom"`
	EffectiveUntil string `yaml:"effectiveUntil"`
	Signed         *bool  `yaml:"signed"`
}

NetworkManifestGovernance describes validity and signature metadata.

type NetworkManifestPolicies ¶ added in v1.6.0

type NetworkManifestPolicies struct {
	Type   string                 `yaml:"type"`
	Source string                 `yaml:"source"`
	Bundle *NetworkManifestBundle `yaml:"bundle"`
	File   *NetworkManifestFile   `yaml:"file"`
}

NetworkManifestPolicies describes the policy artifact referenced by a network manifest.

type NetworkManifestPublisher ¶ added in v1.6.0

type NetworkManifestPublisher struct {
	Role   string `yaml:"role"`
	Domain string `yaml:"domain"`
}

NetworkManifestPublisher identifies the organization publishing the manifest.

type NodeManifest ¶ added in v1.8.0

type NodeManifest struct {
	ManifestVersion string                 `yaml:"manifestVersion"`
	ManifestType    string                 `yaml:"manifestType"`
	SubscriberID    string                 `yaml:"subscriberId"`
	Schema          NodeManifestSchema     `yaml:"schema"`
	Governance      NodeManifestGovernance `yaml:"governance"`
}

NodeManifest is the typed YAML schema for a node-manifest document. It is a sibling to NetworkManifest and shares the same DeDi registry placement convention, signing policy, and manifest loader infrastructure.

SubscriberID is the fully-qualified three-part DeDi reference in the format namespace/registry/recordId — e.g. "nfh.global/subscribers.beckn.one/bpp.energy-provider.com". This corresponds to bapId/bppId in the Beckn transaction context.

func ParseNodeManifest(content []byte) (*NodeManifest, error)

func (m *NodeManifest) Validate(expectedSubscriberID string, now time.Time) error

type NodeManifestGovernance ¶ added in v1.8.0

type NodeManifestGovernance struct {
	EffectiveFrom  string `yaml:"effectiveFrom"`
	EffectiveUntil string `yaml:"effectiveUntil"` // optional — omit for indefinite validity
}

NodeManifestGovernance describes the temporal validity of a node manifest. Unlike NetworkManifestGovernance it carries no Signed field — signature verification is handled by the manifest loader infrastructure.

type NodeManifestSchema ¶ added in v1.8.0

type NodeManifestSchema struct {
	DefaultVersionPolicy string         `yaml:"defaultVersionPolicy,omitempty"`
	SchemaObjects        []SchemaObject `yaml:"schemaObjects"`
}

NodeManifestSchema holds the schema capability declarations for a node manifest.

type RegistryMetadata ¶ added in v1.6.0

type RegistryMetadata struct {
	NamespaceIdentifier string
	RegistryName        string
	RawMeta             map[string]string
}

RegistryMetadata represents metadata configured on a registry itself rather than on a specific record.

type Response ¶

type Response struct {
	Message Message `json:"message"`
}

Response represents the main response structure.

type ResponseStepContext ¶ added in v1.7.0

type ResponseStepContext struct {
	StatusCode int
	Header     http.Header // shared reference — step mutations visible to caller
	Body       []byte      // pre-read response body; nil on publisher path
}

ResponseStepContext carries response-phase data for the response step pipeline. It is constructed by the handler from *http.Response before response steps run, keeping transport types out of the ResponseStep interface.

A nil ResponseStepContext signals the publisher path — ONIX writes the ACK itself and there is no upstream response to inspect.

Header is a shared reference to resp.Header; mutations made by steps (e.g. writing the Signature header) are visible to the handler and forwarded by ReverseProxy without any explicit write-back.

type Role ¶

type Role string

Role defines the type of participant in the network.

const (
	// RoleBAP represents a Buyer App Participant (BAP) in the network.
	RoleBAP Role = "bap"
	// RoleBPP represents a Buyer Platform Participant (BPP) in the network.
	RoleBPP Role = "bpp"
	// RoleGateway represents a Gateway that facilitates communication in the network.
	RoleGateway Role = "gateway"
	// RoleRegistery represents the Registry that maintains network participant details.
	RoleRegistery Role = "registery"
	// RoleDiscovery represents the discovery for that network
	RoleDiscovery Role = "discovery"
)

func (r *Role) UnmarshalYAML(unmarshal func(interface{}) error) error

type Route ¶

type Route struct {
	TargetType  string   // "url" or "publisher"
	PublisherID string   // For message queues
	URL         *url.URL // For API calls
}

Route represents a network route for message processing.

type SchemaObject ¶ added in v1.8.0

type SchemaObject struct {
	Type              string   `yaml:"type"`
	BaseURL           string   `yaml:"baseUrl"`
	SupportedVersions []string `yaml:"supportedVersions"`
	VersionPolicy     string   `yaml:"versionPolicy,omitempty"`
	PinnedVersion     string   `yaml:"pinnedVersion,omitempty"`
}

SchemaObject declares the schema types a node supports, with all accepted versions. BaseURL is the base URL prefix shared by all versions (e.g. "https://.../schema/RetailOffer"). SupportedVersions lists every version the app handles natively — payloads at any of these versions are considered compatible without translation. VersionPolicy controls which version is the canonical translation target:

• "latest" (default) — highest version in SupportedVersions
• "pinned" — the explicit PinnedVersion value

Wire format convention: {BaseURL}/{version}/context.jsonld

func (s *SchemaObject) CanonicalVersion(defaultPolicy string) (string, error)

type SchemaValidationErr ¶

type SchemaValidationErr struct {
	Errors []Error
}

SchemaValidationErr occurs when schema validation errors are encountered.

func (e *SchemaValidationErr) BecknError() *Error

func (e *SchemaValidationErr) Error() string

type Status ¶

type Status string

Status represents the acknowledgment status in a response.

const (
	// StatusACK indicates a successful acknowledgment.
	StatusACK Status = "ACK"
	// StatusNACK indicates a negative acknowledgment or failure.
	StatusNACK Status = "NACK"
)

type StepContext ¶

type StepContext struct {
	context.Context
	Request              *http.Request
	Body                 []byte
	Route                *Route
	SubID                string
	Role                 Role
	RespHeader           http.Header
	ProtocolVersion      string // Protocol version parsed from context.version (e.g. "2.0.0")
	MessageID            string // Message ID parsed from context.messageId in the request body
	InboundAuthSignature string // Raw Base64 signature from the inbound Authorization header's signature="..." attribute
	IsCallerHandler      bool   // True when the handler is a Caller (outbound); false for Receiver (inbound)
}

StepContext holds context information for a request processing step.

func (ctx *StepContext) WithContext(newCtx context.Context)

type Subscriber ¶

type Subscriber struct {
	SubscriberID string `json:"subscriber_id,omitzero"`
	URL          string `json:"url,omitzero" format:"uri"`
	Type         string `json:"type,omitzero" enum:"BAP,BPP,BG"`
	Domain       string `json:"domain,omitzero"`
}

Subscriber represents a unique operational configuration of a trusted platform on a network.

type SubscriberRecord ¶ added in v1.8.0

type SubscriberRecord struct {
	Subscription                   // identity, URL, signing/encryption keys — from data["details"]
	Meta         map[string]string // node manifest metadata — from data["meta"]; may be empty
}

SubscriberRecord is returned by RegistryMetadataLookup.LookupNode. It carries both the subscriber's identity/endpoint data (from the registry details block) and any node-level manifest metadata (from the registry meta block) in a single response, since both come from the same DeDi endpoint call.

type Subscription ¶

type Subscription struct {
	Subscriber         `json:",inline"`
	KeyID              string    `json:"key_id,omitzero" format:"uuid"`
	SigningPublicKey   string    `json:"signing_public_key,omitzero"`
	EncrPublicKey      string    `json:"encr_public_key,omitzero"`
	ValidFrom          time.Time `json:"valid_from,omitzero" format:"date-time"`
	ValidUntil         time.Time `json:"valid_until,omitzero" format:"date-time"`
	Status             string    `json:"status,omitzero" enum:"INITIATED,UNDER_SUBSCRIPTION,SUBSCRIBED,EXPIRED,UNSUBSCRIBED,INVALID_SSL"`
	Created            time.Time `json:"created,omitzero" format:"date-time"`
	Updated            time.Time `json:"updated,omitzero" format:"date-time"`
	Nonce              string    `json:"nonce,omitzero"`
	NetworkMemberships []string  `json:"network_memberships,omitempty"`
}

Subscription represents subscription details of a network participant.