definition

type Cache interface {
	// Get retrieves a value from the cache based on the given key.
	Get(ctx context.Context, key string) (string, error)

	// Set stores a value in the cache with the given key and TTL (time-to-live) in seconds.
	Set(ctx context.Context, key, value string, ttl time.Duration) error

	// Delete removes a value from the cache based on the given key.
	Delete(ctx context.Context, key string) error

	// Clear removes all values from the cache.
	Clear(ctx context.Context) error
}

type CacheProvider interface {
	// New initializes a new cache instance with the given configuration.
	New(ctx context.Context, config map[string]string) (Cache, func() error, error)
}

type Decrypter interface {
	// Decrypt decrypts the given body using the provided privateKeyBase64 and publicKeyBase64.
	Decrypt(ctx context.Context, encryptedData string, privateKeyBase64, publicKeyBase64 string) (string, error)
}

type DecrypterProvider interface {
	// New creates a new decrypter instance based on the provided config.
	New(ctx context.Context, config map[string]string) (Decrypter, func() error, error)
}

type Encrypter interface {
	// Encrypt encrypts the given body using the provided privateKeyBase64 and publicKeyBase64.
	Encrypt(ctx context.Context, data string, privateKeyBase64, publicKeyBase64 string) (string, error)
}

type EncrypterProvider interface {
	// New creates a new encrypter instance based on the provided config.
	New(ctx context.Context, config map[string]string) (Encrypter, func() error, error)
}

type KeyManager interface {
	GenerateKeyset() (*model.Keyset, error)
	InsertKeyset(ctx context.Context, keyID string, keyset *model.Keyset) error
	Keyset(ctx context.Context, keyID string) (*model.Keyset, error)
	LookupNPKeys(ctx context.Context, subscriberID, uniqueKeyID string) (signingPublicKey string, encrPublicKey string, err error)
	DeleteKeyset(ctx context.Context, keyID string) error
}

type KeyManagerProvider interface {
	New(context.Context, RegistryLookup, map[string]string) (KeyManager, func() error, error)
}

type ManifestLoader interface {
	GetByNetworkID(ctx context.Context, networkID string) (*model.ManifestDocument, error)
	GetByMetadata(ctx context.Context, metadata model.ManifestMetadata) (*model.ManifestDocument, error)
}

type ManifestLoaderProvider interface {
	New(context.Context, Cache, RegistryMetadataLookup, map[string]string) (ManifestLoader, func() error, error)
}

type MiddlewareProvider interface {
	New(ctx context.Context, cfg map[string]string) (func(http.Handler) http.Handler, error)
}

type OtelSetupMetricsProvider interface {
	// New initializes a new telemetry provider instance with the given configuration.
	New(ctx context.Context, config map[string]string) (*telemetry.Provider, func() error, error)
}

type PayloadEntry struct {
	MessageID     string
	TransactionID string
	NetworkID     string
	Action        string
	SubscriberID  string
	Role          model.Role
	RequestBody   []byte // nil when StoreBody: false
	Signature     string // raw Authorization header; empty when StoreSignature: false
	StoredAt      time.Time
	ExpiresAt     time.Time
}

type PayloadStore interface {
	// Store persists an entry built from the incoming request's StepContext.
	Store(ctx *model.StepContext) error

	// GetByTransactionID returns all entries for a transaction in StoredAt ascending order.
	// Returns nil (not an error) if the transaction is unknown or expired.
	GetByTransactionID(ctx context.Context, transactionID string) ([]PayloadEntry, error)

	// GetByMessageID returns the entry for the given message ID scoped to an action.
	// Returns nil (not an error) if not found or if the action does not match.
	GetByMessageID(ctx context.Context, messageID, action string) (*PayloadEntry, error)

	// Exists is an O(1) check for dedup / replay protection.
	Exists(ctx context.Context, messageID string) (bool, error)
}

type PayloadStoreProvider interface {
	New(ctx context.Context, cache Cache, namespace string, cfg map[string]string) (PayloadStore, func() error, error)
}

type PolicyChecker interface {
	CheckPolicy(ctx *model.StepContext) error
}

type PolicyCheckerProvider interface {
	New(ctx context.Context, manifestLoader ManifestLoader, config map[string]string) (PolicyChecker, func(), error)
}

type Publisher interface {
	// Publish sends a message (as a byte slice) using the underlying messaging system.
	Publish(context.Context, string, []byte) error
}

type PublisherProvider interface {
	// New initializes a new publisher instance with the given configuration.
	New(ctx context.Context, config map[string]string) (Publisher, func() error, error)
}

type RegistryLookup interface {
	// looks up Registry entry to obtain public keys to validate signature of the incoming message
	Lookup(ctx context.Context, req *model.Subscription) ([]model.Subscription, error)
}

type RegistryLookupProvider interface {
	New(context.Context, Cache, map[string]string) (RegistryLookup, func() error, error)
}

type RegistryMetadataLookup interface {
	LookupRegistry(ctx context.Context, namespaceIdentifier, registryName string) (*model.RegistryMetadata, error)
}

type ResponseStep interface {
	RunOnResponse(ctx *model.StepContext, rctx *model.ResponseStepContext) error
}

type Router interface {
	// Route determines the routing destination based on the request context.
	Route(ctx context.Context, url *url.URL, body []byte) (*model.Route, error)
}

type RouterProvider interface {
	New(ctx context.Context, config map[string]string) (Router, func() error, error)
}

type SchemaValidator interface {
	Validate(ctx context.Context, url *url.URL, payload []byte) error
}

type SchemaValidatorProvider interface {
	New(ctx context.Context, config map[string]string) (SchemaValidator, func() error, error)
}

type SignValidator interface {
	// Validate verifies the 3-line signing string for inbound requests.
	// The request body is available as ctx.Body.
	// checkIdentity controls whether the signer's subscriber ID (from keyId) is
	// matched against the caller identity declared in the request body context.
	// Pass true for subscriber Authorization headers, false for gateway headers.
	Validate(ctx *model.StepContext, header string, publicKeyBase64 string, checkIdentity bool) error

	// ValidateAck verifies a Beckn v2.0.0 AckSignature per NFH-004 §3.4.
	// The four-line signing string is:
	//   (created): <ts>
	//   (expires): <ts>
	//   digest: BLAKE-512=<base64(blake2b512(body))>
	//   request-signature: <outboundAuthSignature>
	// outboundAuthSignature is the raw Base64 signature value from the original
	// outbound Authorization header's signature="..." attribute. If empty the
	// fourth line is omitted (matches the ackSigner signing-string construction).
	// body is passed explicitly because different call sites hash different bodies:
	// solicited callback bodies differ from synchronous ACK response bodies.
	// checkIdentity: true for solicited callbacks (step.go), false for ACK responses (responsestep.go).
	ValidateAck(ctx *model.StepContext, body []byte, signatureHeader, outboundAuthSignature, publicKeyBase64 string, checkIdentity bool) error
}

type SignValidatorProvider interface {
	// New creates a new Verifier instance based on the provided config.
	New(ctx context.Context, config map[string]string) (SignValidator, func() error, error)
}

type Signer interface {
	// Sign generates a signature for the given body and privateKeyBase64.
	// The signature is created with the given timestamps: createdAt (signature creation time)
	// and expiresAt (signature expiration time).
	Sign(ctx context.Context, body []byte, privateKeyBase64 string, createdAt, expiresAt int64) (string, error)

	// SignAck generates a signature for a synchronous Ack response using the
	// NFH-004 §3.4 four-line signing string:
	//   (created): <ts>
	//   (expires): <ts>
	//   digest: BLAKE-512=<base64(blake2b512(ackBody))>
	//   request-signature: <requestSignature>
	// requestSignature is the raw Base64 value from the inbound Authorization
	// header's signature="..." attribute. If empty the fourth line is omitted.
	SignAck(ctx context.Context, ackBody []byte, requestSignature, privateKeyBase64 string, createdAt, expiresAt int64) (string, error)
}

type SignerProvider interface {
	// New creates a new signer instance based on the provided config.
	New(ctx context.Context, config map[string]string) (Signer, func() error, error)
}

type Step interface {
	Run(ctx *model.StepContext) error
}

type StepProvider interface {
	New(context.Context, map[string]string) (Step, func(), error)
}

type TransportWrapper interface {
	// Wrap takes a base transport and returns a new transport that wraps it.
	Wrap(base http.RoundTripper) http.RoundTripper
}

type TransportWrapperProvider interface {
	New(ctx context.Context, config map[string]any) (TransportWrapper, func(), error)
}