a4-cli 0.45.0

//! Generated by a4 from protocol package `local-tip-jar` 0.1.0 (arete.protocol-spec/v1 `localTipJar`). Do not edit.
//!
//! Local development fixture: two templated System Program transfers.
//!
//! Create a client with [`LocalTipJarPublishableClient`] (publishable key, `public` steps
//! only) or [`LocalTipJarSecretClient`] (secret key, every client-callable step).

use arete_sdk::protocol;
pub use arete_sdk::protocol::{
    verify_webhook, ProtocolClient, ProtocolClientOptions, ProtocolError, ProtocolInteger,
    ProtocolPrepareOptions, ProtocolPrepareResult, ProtocolPrepared, ProtocolRejection,
    ProtocolRejectionCode,
};

/// The stacks this protocol reads, as `a4 install stack --rust` generates them.
pub mod stacks {}

/// The programs this protocol uses, as `a4 install program --rust` generates them.
pub mod programs {}

/// States of the instance machine.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum LocalTipJarInstanceState {
    #[serde(rename = "closed")]
    Closed,
    #[serde(rename = "open")]
    Open,
}

impl LocalTipJarInstanceState {
    pub const ALL: [Self; 2] = [Self::Closed, Self::Open];

    /// The name on the wire.
    pub fn as_wire(self) -> &'static str {
        match self {
            Self::Closed => "closed",
            Self::Open => "open",
        }
    }

    /// The variant named `wire`, if this release knows it.
    pub fn from_wire(wire: &str) -> Option<Self> {
        match wire {
            "closed" => Some(Self::Closed),
            "open" => Some(Self::Open),
            _ => None,
        }
    }
}

impl LocalTipJarInstanceState {
    /// The state of a read instance, if this release knows it.
    pub fn of(instance: &protocol::ProtocolInstanceSummary) -> Option<Self> {
        Self::from_wire(&instance.state)
    }

    /// No step leaves this state.
    pub fn is_terminal(self) -> bool {
        matches!(self, Self::Closed)
    }
}

/// Parameters an instance is created with.
#[derive(Debug, Clone, PartialEq, Default, serde::Serialize, serde::Deserialize)]
pub struct LocalTipJarParams {
    /// Format: `u64`.
    pub amount: ProtocolInteger,
}

/// Arguments of the `close` step.
#[derive(Debug, Clone, PartialEq, Default, serde::Serialize, serde::Deserialize)]
pub struct LocalTipJarCloseArgs {
    /// Format: `u64`.
    pub amount: ProtocolInteger,
}

/// Arguments of the `open` step.
#[derive(Debug, Clone, PartialEq, Default, serde::Serialize, serde::Deserialize)]
pub struct LocalTipJarOpenArgs {
    /// Format: `u64`.
    pub amount: ProtocolInteger,
    /// Format: `pubkey`.
    pub recipient: String,
}

/// An instance's metadata document: the fields written so far.
#[derive(Debug, Clone, PartialEq, Default, serde::Serialize, serde::Deserialize)]
pub struct LocalTipJarInstanceMetadata {}

/// A participant's metadata document: the fields written so far.
#[derive(Debug, Clone, PartialEq, Default, serde::Serialize, serde::Deserialize)]
pub struct LocalTipJarParticipantMetadata {}

impl LocalTipJarInstanceMetadata {
    /// Read a metadata document.
    pub fn from_map(
        metadata: &serde_json::Map<String, serde_json::Value>,
    ) -> Result<Self, serde_json::Error> {
        serde_json::from_value(serde_json::Value::Object(metadata.clone()))
    }

    /// The fields set here, as a merge patch for `update_metadata`.
    pub fn to_patch(&self) -> serde_json::Map<String, serde_json::Value> {
        match serde_json::to_value(self) {
            Ok(serde_json::Value::Object(patch)) => patch,
            _ => serde_json::Map::new(),
        }
    }
}

impl LocalTipJarParticipantMetadata {
    /// Read a metadata document.
    pub fn from_map(
        metadata: &serde_json::Map<String, serde_json::Value>,
    ) -> Result<Self, serde_json::Error> {
        serde_json::from_value(serde_json::Value::Object(metadata.clone()))
    }

    /// The fields set here, as a merge patch for `update_metadata`.
    pub fn to_patch(&self) -> serde_json::Map<String, serde_json::Value> {
        match serde_json::to_value(self) {
            Ok(serde_json::Value::Object(patch)) => patch,
            _ => serde_json::Map::new(),
        }
    }
}

/// Guard codes the `close` step can reject with, in evaluation order.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum LocalTipJarCloseGuardCode {
    NotRecipient,
    NotOpen,
}

impl LocalTipJarCloseGuardCode {
    pub const ALL: [Self; 2] = [Self::NotRecipient, Self::NotOpen];

    /// The name on the wire.
    pub fn as_wire(self) -> &'static str {
        match self {
            Self::NotRecipient => "not_recipient",
            Self::NotOpen => "not_open",
        }
    }

    /// The variant named `wire`, if this release knows it.
    pub fn from_wire(wire: &str) -> Option<Self> {
        match wire {
            "not_recipient" => Some(Self::NotRecipient),
            "not_open" => Some(Self::NotOpen),
            _ => None,
        }
    }
}

impl protocol::ProtocolGuardCode for LocalTipJarCloseGuardCode {
    fn from_wire(wire: &str) -> Option<Self> {
        Self::from_wire(wire)
    }

    fn as_wire(&self) -> &str {
        (*self).as_wire()
    }
}

/// Guard codes the `open` step can reject with, in evaluation order.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum LocalTipJarOpenGuardCode {
    AmountZero,
}

impl LocalTipJarOpenGuardCode {
    pub const ALL: [Self; 1] = [Self::AmountZero];

    /// The name on the wire.
    pub fn as_wire(self) -> &'static str {
        match self {
            Self::AmountZero => "amount_zero",
        }
    }

    /// The variant named `wire`, if this release knows it.
    pub fn from_wire(wire: &str) -> Option<Self> {
        match wire {
            "amount_zero" => Some(Self::AmountZero),
            _ => None,
        }
    }
}

impl protocol::ProtocolGuardCode for LocalTipJarOpenGuardCode {
    fn from_wire(wire: &str) -> Option<Self> {
        Self::from_wire(wire)
    }

    fn as_wire(&self) -> &str {
        (*self).as_wire()
    }
}

/// Events the protocol emits, on the event stream and to webhooks.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum LocalTipJarEvent {
    TipJarClosed,
}

impl LocalTipJarEvent {
    pub const ALL: [Self; 1] = [Self::TipJarClosed];

    /// The name on the wire.
    pub fn as_wire(self) -> &'static str {
        match self {
            Self::TipJarClosed => "tipJar.closed",
        }
    }

    /// The variant named `wire`, if this release knows it.
    pub fn from_wire(wire: &str) -> Option<Self> {
        match wire {
            "tipJar.closed" => Some(Self::TipJarClosed),
            _ => None,
        }
    }
}

impl LocalTipJarEvent {
    /// The machine the event belongs to.
    pub fn machine(self) -> protocol::ProtocolMachineKind {
        match self {
            Self::TipJarClosed => protocol::ProtocolMachineKind::Instance,
        }
    }

    /// The event a webhook payload carries, if this release knows it.
    pub fn of(payload: &protocol::ProtocolEventPayloadV1) -> Option<Self> {
        Self::from_wire(&payload.event)
    }
}

/// The `localTipJar` protocol and the deployment this client calls.
pub const LOCAL_TIP_JAR_PROTOCOL: protocol::ProtocolDefinition = protocol::ProtocolDefinition {
    name: "localTipJar",
    version: "0.1.0",
    package: "local-tip-jar",
    package_release_hash: "arete:h1:protocol-release:sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    protocol_spec_hash: "arete:h1:protocol-spec:sha256:f1a6580e1d2259ca7da870e33e0a1920ea0704cf2014efccf29116c4abc06032",
    protocol_release_hash: "arete:h1:protocol-release:sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    deployment: protocol::ProtocolDeploymentDescriptor {
        deployment_id: "dep-local-1",
        access: protocol::ProtocolDeploymentAccess::Private,
        api_url: "https://api.example.test/api",
        session_endpoint: "https://api.example.test/ws/sessions",
    },
    instance_visibility: protocol::ProtocolInstanceVisibility::Shared,
    steps: &[
        protocol::ProtocolStepDefinition {
            name: "close",
            scope: protocol::ProtocolStepScope::Instance,
            access: protocol::ProtocolStepAccess::Secret,
            guards: &["not_recipient", "not_open"],
            args: &["amount"],
        },
        protocol::ProtocolStepDefinition {
            name: "open",
            scope: protocol::ProtocolStepScope::Create,
            access: protocol::ProtocolStepAccess::Secret,
            guards: &["amount_zero"],
            args: &["amount", "recipient"],
        },
    ],
    events: &[
        protocol::ProtocolEventDefinition { name: "tipJar.closed", machine: protocol::ProtocolMachineKind::Instance },
    ],
    instance_metadata: &[],
    participant_metadata: &[],
    live_stack: None,
};

/// A client for a publishable key (`a4_pk_...`): it can prepare the `public`
/// steps only.
///
/// Reads, submit, metadata and the event stream come from [`ProtocolClient`]
/// through `Deref`.
#[derive(Debug, Clone)]
pub struct LocalTipJarPublishableClient {
    client: ProtocolClient,
}

impl LocalTipJarPublishableClient {
    /// Authenticate with a publishable key.
    pub fn new(publishable_key: impl Into<String>) -> Result<Self, ProtocolError> {
        Self::with_options(ProtocolClientOptions::default().with_publishable_key(publishable_key))
    }

    /// Full options: tokens, token providers, URL overrides, an HTTP client.
    pub fn with_options(mut options: ProtocolClientOptions) -> Result<Self, ProtocolError> {
        options.key_class = Some(protocol::ProtocolKeyClass::Publishable);
        Ok(Self {
            client: ProtocolClient::new(&LOCAL_TIP_JAR_PROTOCOL, options)?,
        })
    }

    /// A client on `session`'s auth whose instance handles follow the
    /// session's stack members; see `Session::protocol_client`.
    pub fn from_session(
        session: &arete_sdk::Session,
        mut options: ProtocolClientOptions,
    ) -> Result<Self, ProtocolError> {
        options.key_class = Some(protocol::ProtocolKeyClass::Publishable);
        Ok(Self {
            client: session.protocol_client(&LOCAL_TIP_JAR_PROTOCOL, options)?,
        })
    }

    /// The untyped client.
    pub fn client(&self) -> &ProtocolClient {
        &self.client
    }

    /// Load an instance and keep it current from its event stream.
    ///
    /// This protocol publishes no live stack view.
    pub async fn instance_handle(
        &self,
        instance: &str,
    ) -> Result<protocol::ProtocolInstanceHandle, ProtocolError> {
        self.client.instance_handle(instance).await
    }
}

impl std::ops::Deref for LocalTipJarPublishableClient {
    type Target = ProtocolClient;

    fn deref(&self) -> &ProtocolClient {
        &self.client
    }
}

/// A client for a secret or agent key (`a4_sk_...`, `a4_ak_...`): it can prepare
/// every client-callable step. Keep it on servers.
///
/// Reads, submit, metadata and the event stream come from [`ProtocolClient`]
/// through `Deref`.
#[derive(Debug, Clone)]
pub struct LocalTipJarSecretClient {
    client: ProtocolClient,
}

impl LocalTipJarSecretClient {
    /// Authenticate with a secret or agent key.
    pub fn new(secret_key: impl Into<String>) -> Result<Self, ProtocolError> {
        Self::with_options(ProtocolClientOptions::default().with_secret_key(secret_key))
    }

    /// Authenticate with `ARETE_API_KEY`, or else the `a4` CLI login.
    pub fn from_env() -> Result<Self, ProtocolError> {
        Self::with_options(ProtocolClientOptions::default())
    }

    /// Full options: tokens, token providers, URL overrides, an HTTP client.
    pub fn with_options(mut options: ProtocolClientOptions) -> Result<Self, ProtocolError> {
        options.key_class = Some(protocol::ProtocolKeyClass::Secret);
        Ok(Self {
            client: ProtocolClient::new(&LOCAL_TIP_JAR_PROTOCOL, options)?,
        })
    }

    /// A client on `session`'s auth whose instance handles follow the
    /// session's stack members; see `Session::protocol_client`.
    pub fn from_session(
        session: &arete_sdk::Session,
        mut options: ProtocolClientOptions,
    ) -> Result<Self, ProtocolError> {
        options.key_class = Some(protocol::ProtocolKeyClass::Secret);
        Ok(Self {
            client: session.protocol_client(&LOCAL_TIP_JAR_PROTOCOL, options)?,
        })
    }

    /// The untyped client.
    pub fn client(&self) -> &ProtocolClient {
        &self.client
    }

    /// Load an instance and keep it current from its event stream.
    ///
    /// This protocol publishes no live stack view.
    pub async fn instance_handle(
        &self,
        instance: &str,
    ) -> Result<protocol::ProtocolInstanceHandle, ProtocolError> {
        self.client.instance_handle(instance).await
    }

    /// Prepare `close` (instance step, role `recipient` authority): Close the tip jar.
    ///
    /// Resolves with the intent and the transactions for `wallet` to sign, or
    /// with a rejection carrying a [`LocalTipJarCloseGuardCode`] or an access code.
    pub async fn prepare_close(
        &self,
        instance: &str,
        wallet: &str,
        args: &LocalTipJarCloseArgs,
        options: ProtocolPrepareOptions,
    ) -> Result<ProtocolPrepareResult<LocalTipJarCloseGuardCode>, ProtocolError> {
        self.client
            .prepare("close", Some(instance), wallet, args, options)
            .await
    }

    /// Prepare `open` (create step, creator authority): Open a tip jar.
    ///
    /// Resolves with the intent and the transactions for `wallet` to sign, or
    /// with a rejection carrying a [`LocalTipJarOpenGuardCode`] or an access code.
    pub async fn prepare_open(
        &self,
        wallet: &str,
        args: &LocalTipJarOpenArgs,
        options: ProtocolPrepareOptions,
    ) -> Result<ProtocolPrepareResult<LocalTipJarOpenGuardCode>, ProtocolError> {
        self.client
            .prepare("open", None, wallet, args, options)
            .await
    }
}

impl std::ops::Deref for LocalTipJarSecretClient {
    type Target = ProtocolClient;

    fn deref(&self) -> &ProtocolClient {
        &self.client
    }
}

/// A webhook delivery of this protocol's events; read its event with [`LocalTipJarEvent::of`].
pub type LocalTipJarWebhookPayload = protocol::ProtocolEventPayloadV1;

/// Verify a signed webhook delivery for this protocol's events. Pass the raw
/// request body exactly as received.
pub fn verify_local_tip_jar_webhook(
    secret: impl AsRef<[u8]>,
    body: impl AsRef<[u8]>,
    headers: &(impl protocol::WebhookHeaders + ?Sized),
    options: protocol::VerifyWebhookOptions,
) -> Result<protocol::VerifiedWebhook<LocalTipJarWebhookPayload>, protocol::WebhookVerificationError> {
    protocol::verify_webhook(secret, body, headers, options)
}