Generate and use an SDK client#

This recipe exports exact Rust and TypeScript clients from one accepted Build and uses them without reimplementing Planning, Build, Deployment, or Authority.

The language APIs and outputs below are illustrative end-product examples.

1. Export receipted clients#

A client SDK is an ordinary language projection. one export generated selects one by its owner-qualified projection or profile identity and writes the exact bytes, inspection evidence, and projection receipt as one bundle. --list prints every projection retained by an authorized realized Build report, so no artifact digest is required; the exact artifact:sha256:<digest> identifier remains available for byte-exact selection.

$ one export generated --build-report build-report.json --list
one.projection.rust#Client@1        artifact:sha256:aa31…  …
one.projection.typescript#Sdk@1     artifact:sha256:c124…  …

$ one export generated --build-report build-report.json \
    --profile one.projection.rust#Client@1 --destination rust-client
$ one export generated --build-report build-report.json \
    --profile one.projection.typescript#Sdk@1 --destination typescript-client

Each projection records the contract revision, profile, toolchain, generated files, unsupported features, and loss.

2. Call the operation from Rust#

use parcelhub_orders::{Client, GetOrderRequest, OrderResult};

let result = Client::from_binding(binding)
    .orders()
    .get(GetOrderRequest { customer_id, order_id })
    .await?;

match result {
    OrderResult::Succeeded(order) => show(order),
    OrderResult::Rejected(fault) => show_domain_fault(fault),
    OrderResult::Denied(denial) => request_access(denial),
    OrderResult::Failed(failure) => show_recovery(failure),
}

3. Call the same operation from TypeScript#

import { OrdersClient } from "@parcelhub/orders";

const result = await OrdersClient.fromBinding(binding).orders.get({
  customerId,
  orderId,
});

switch (result.kind) {
  case "succeeded": return show(result.value);
  case "rejected": return showDomainFault(result.fault);
  case "denied": return requestAccess(result.denial);
  case "failed": return showRecovery(result.failure);
}

Bindings supply an exact selected protocol endpoint and client credential reference. Generated code never discovers a service, embeds a secret, selects a provider, or treats transport success as domain success. Variant spellings follow each target's conventions, but every outer result maps one-to-one to the intended classes in the failure model; a projection never invents a synonym for Success.

4. Verify projection parity#

one test --root OrdersRustClient --scenario ocs-conformance
one test --root OrdersTypeScriptClient --scenario ocs-conformance

Capability levels and loss#

A generated client is one capability level, not full language support. The same OCS contract can be projected as nominal values, a client, service and activity bindings, or a complete implementation-body language; each level requires its own profile, tooling, conformance, and runtime evidence. A client projection never implies that the target language may host implementation bodies.

Every projection records the contract revision, source-language and projection profiles, toolchain, generated files, source maps, runtime support, unsupported features, and exhaustive preservation or loss dispositions. Loss is explicit: a target that cannot represent an optional field, a discriminant, or a bounded quantity reports it rather than silently widening or dropping it. See the OCS contract and packaging and boundaries.

Executable evidence#

The checked-in ParcelHub project owns a receipted generated Rust contract/client SDK and its codec test:

cargo test -p parcelhub --test generated_sdk

The one export generated and language-call forms above remain illustrative end-product syntax.

See languages and SDKs.