Skip to content
Gestalt

TypeScript SDK

Status: fixture-rehearsed against the live cloud and shape-only via built-in fixture fetch. Source: sdk/ts/src/index.ts.

Install

Section titled “Install”

For local development, link or use the workspace directly:

Terminal window
cd sdk/ts
npm install
npm run build

Then in your Koerper:

Terminal window
npm install file:../../path/to/sdk/ts

When the SDK is published, it will live as @gestalt/sdk.

Construct the client

Section titled “Construct the client”
import { GestaltClient } from "@gestalt/sdk";


const client = new GestaltClient({
  baseUrl: "http://127.0.0.1:3011",
  token: "fixture-session-token",
});

Options:

interface GestaltClientOptions {
  baseUrl: string;
  token?: string;            // bearer token; required for most endpoints
  fetchImpl?: typeof fetch;  // override (e.g. for createFixtureFetch())
}

Outcomes and receipts

Section titled “Outcomes and receipts”

Every call returns a MembraneResponse<T>:

interface MembraneResponse<T> {
  operation: string;
  outcome: MembraneOutcome;
  body: T;
  receipt?: MembraneReceipt;
}


type MembraneOutcome =
  | "admitted" | "refused" | "pending" | "projected"
  | "verified" | "queued" | "executed" | "failed";


interface MembraneReceipt {
  ref: GestaltRef;
  outcome: MembraneOutcome;
  reasons: string[];
  signature?: string;
  fixture?: boolean;
}

Today every receipt carries fixture: true. See ../concepts/receipts-and-proofs.md.

Method index

Section titled “Method index”

GestaltClient exposes 93 methods today. Most return Promise<MembraneResponse<unknown>>; a few families return richer body types that are exported alongside the request types (for example StandingClaimBody). When you need a refined body type that is not yet exported, narrow the response from unknown at the call site rather than asserting as upstream.

FamilyMethods
Tenant and sessiontenantSelf, tenantCreate, companyBootstrap
AuthauthLoginStart, authLoginFinish, authSessionIssue, authSessionInspect, authSessionRefresh, authRateLimitEvaluate, authRecoveryPolicy, authRecoveryExecute
HumanAuth and passkeyshumanAuthChallenge, humanAuthPasskeyRegistrationOptions, humanAuthPasskeyAssertionOptions, humanAuthRegisterPasskey, humanAuthPasskeyImport, humanAuthVerifyPasskey, humanAuthPasskeyRevoke, humanAuthPasskeyRotate, humanAuthFaceMatch, m13PresenceApproval, m13SessionRevoke, m13KeyRotate
Key custody and production gatekeyCustodyReadiness, keyCustodyAttest, keyCustodyProviderAttest, keyCustodyRotationRehearse, keyCustodyRevoke, keyCustodyBreakGlass, keyCustodySigningRehearse, productionAdmissionPolicy, productionAdmissionPrecheck, stagingMaturityReport, tenantOnboardingGate, pilotAdmissionGate
Standing and mandatesstandingClaim, standingEvaluate, standingGrant, standingRevoke, mandateDelegate, mandateRevoke
Advisor, lens, interventionadvisorOpenMatter, advisorIssueOpinion, advisorRequestEvidence, lensScope, lensDisclose, interventionRequest, interventionIssue
Intents and shopprecheckIntent, prepareShop, commitShop
Capabilities and authoritycapabilityPublish, capabilityPolicyEvaluate, resolveAuthorityContext, packageImport, packagePublisherOnboard, packageReviewerOnboard, packageCandidate, packageReview, packageActivate, packageRevoke
OpsopsEdgePolicyCheck, opsRestoreRehearse, opsIncidentReceipt, opsStatus
Evidence and connectorsconnectorConsent, connectorEvidenceIngest, connectorRevoke, connectorEvidenceStatus
Effects and economyeffectIntent, effectDispatch, economicInvoice, economicPaymentObservation, economicBookkeepingFact, economicPeriodClose
Proofs and receiptsrequestProof, requestProofBundle, verifyProofBundle, verifyReceipt
Reality and zeitgestaltrealityFork, realityDiff, realityPromote, realityDiscard, zeitgestaltQuery
Read modelsreadActiveStandings, readActiveMandates, readPeriodCloseReadiness, readConnectorEvidenceGaps, readProofHistory
Observability and refusalrecentCommits, m7State, refusalCodes, refusalRegistry

Routes without an SDK wrapper today (call the membrane directly when needed):

/v1/auth/session/exchange              fixture bearer -> signed session context
/v1/authority/operators/grant          hosted operator delegation
/v1/authority/operators/revoke         hosted operator revocation
/v1/authority/packages/status          package lifecycle + Verlag trust roots
/v1/closure/surface                    closure / tension emission
/v1/companies/production-lifecycle/advance  production gate (companies)
/v1/evidence/witness-fixture           fixture witness ingest
/v1/intents/commit                     commit signed fixture atom
/v1/membrane/contract                  membrane contract introspection
/v1/production/scope                   production v0 boundary contract
/v1/production/scope/evaluate          bounded admission decision for a candidate operation
/v1/reality/commit                     projected atom rehearsal
/v1/tenants/production-lifecycle/advance  production gate (tenants)
/v1/tensions/query                     tension queries
/v1/verticals/de/invoice-payment-advisor  DE invoice/payment/advisor walk

The illustrative examples below cover the most common families. For the full set of request shapes, see sdk/ts/src/index.ts. For capability-state labels and refusal posture, see ../api/README.md and ../reference/capability-state.md.

Selected examples

Section titled “Selected examples”

All methods return Promise<MembraneResponse<unknown>> unless noted. Specific response shapes vary by operation.

Tenant

Section titled “Tenant”
client.tenantSelf()

Get tenant context for the bearer-bound session. See ../api/observability-and-misc.md.

Intents and commits

Section titled “Intents and commits”
client.precheckIntent({
  tenant: "tenant_node:rheinwerk_calibration",
  capability: "capability:issue_invoice_fixture_v1",
  action: "issue",
  evidence: ["evidence_bundle:invoice_payload"],
});

See ../api/intents-and-commits.md.

Authority

Section titled “Authority”
client.resolveAuthorityContext({
  subjectCompany: "company_geist:rheinwerk_calibration",
  effectiveContext: "effective_context:fixture_de_gmbh",
  to: ["FR"],
  tags: ["warehouse_country:FR"],
  evidenceRefs: [],
});


client.packageImport({...});
client.packageCandidate({...});
client.packageReview({...});
client.packageActivate({...});
client.packageRevoke({...});

See ../api/authority.md.

Capabilities

Section titled “Capabilities”
client.capabilityPublish({
  tenant: "tenant_node:rheinwerk_calibration",
  // ... capability manifest fields
});


client.capabilityPolicyEvaluate({
  tenant: "tenant_node:rheinwerk_calibration",
  capability: "capability:published_fixture_capability_v1",
  // ... evaluation context
});

See ../api/capabilities.md.

Shop (hosted operator delegate)

Section titled “Shop (hosted operator delegate)”
client.prepareShop({
  tenant: "tenant_node:rheinwerk_calibration",
  capability: "capability:issue_invoice_fixture_v1",
  action: "issue",
  evidence: [],
});


client.commitShop({...});

See ../api/shop.md.

Reality

Section titled “Reality”
client.realityFork({
  tenant: "tenant_node:rheinwerk_calibration",
  purpose: "march close what-if",
});


client.realityDiff({
  tenant: "tenant_node:rheinwerk_calibration",
  reality: "reality:m6_projection_repair",
  evidence: [],
});


client.realityPromote({...});
client.realityDiscard({...});

See ../api/reality.md.

Effects

Section titled “Effects”
client.effectIntent({
  tenant: "tenant_node:rheinwerk_calibration",
  subject: "company_geist:rheinwerk_calibration",
  effect_kind: "send_invoice_email",
  adapter: "fixture_email_adapter",
  mode: "fire_and_record",
  idempotency_key: "invoice-2026-04-001-email",
  evidence: ["evidence_bundle:invoice_payload"],
  human_presence_receipt: "human_presence_receipt:fixture_private_presence",
});


client.effectDispatch({
  tenant: "tenant_node:rheinwerk_calibration",
  effect_intent: "effect_intent:...",
  idempotency_key: "...",
});

See ../api/effects.md.

Economy

Section titled “Economy”
client.economicInvoice({
  tenant: "tenant_node:rheinwerk_calibration",
  amount_cents: 11900,
  currency: "EUR",
  evidence: ["evidence_bundle:invoice_payload"],
});


client.economicPaymentObservation({
  tenant: "tenant_node:rheinwerk_calibration",
  invoice: "invoice:...",
  amount_cents: 11900,
  currency: "EUR",
  evidence: ["evidence_bundle:payment_observation"],
});


client.economicBookkeepingFact({
  tenant: "tenant_node:rheinwerk_calibration",
  invoice: "invoice:...",
  payment_observation: "payment_observation:...",
  advisor_evidence: "evidence_bundle:steuerberater_review",
});


client.economicPeriodClose({
  tenant: "tenant_node:rheinwerk_calibration",
  period: "2026-04",
  evidence: ["evidence_bundle:closure_clearance"],
});

See ../api/economy.md.

Evidence (connectors)

Section titled “Evidence (connectors)”
client.connectorEvidenceIngest({
  tenant: "tenant_node:rheinwerk_calibration",
  subject: "company_geist:rheinwerk_calibration",
  kind: "invoice",      // | payment | bookkeeping | advisor | registry | ...
  idempotency_key: "ingest-001",
  source_system: "fixture_connector",
  source_label: "fixture",
  source_hash: "sha256:...",
  raw_kind: "fixture_json",
  claims: ["invoice_payload"],
  amount_cents: 11900,
  currency: "EUR",
  fixture: true,
});


client.connectorEvidenceStatus();

See ../api/evidence.md.

Proofs and receipts

Section titled “Proofs and receipts”
client.requestProof({
  tenant: "tenant_node:rheinwerk_calibration",
  subjectCompany: "company_geist:rheinwerk_calibration",
  scope: "advisor_review",  // | self_audit | external_counterparty
  fields: ["invoice", "payment_observation", "advisor_opinion"],
  purpose: "Q1 2026 Steuerberater review",
});


client.requestProofBundle({
  tenant: "tenant_node:rheinwerk_calibration",
  entitlement: "entitlement:...",
});


client.verifyReceipt(receipt);

Plus the standalone helper:

import { verifyFixtureReceipt } from "@gestalt/sdk";
const result = verifyFixtureReceipt(receipt);
// { verified: true, fixture: true, reasons: [...] }

See ../api/proofs-and-receipts.md.

Human auth

Section titled “Human auth”
client.humanAuthChallenge({
  tenant: "tenant_node:rheinwerk_calibration",
  subject: "human_person:anna",
  relying_party_id: "gestalt.local",
  scopes: ["sensitive_approval"],
});


client.humanAuthVerifyPasskey({
  tenant: "tenant_node:rheinwerk_calibration",
  challenge: "human_auth_challenge:...",
  passkey_binding: "passkey_binding:anna_platform_passkey_fixture",
  relying_party_id: "gestalt.local",
  user_verified: true,
  credential_id_hash: "sha256:...",
});


client.humanAuthFaceMatch({
  tenant: "tenant_node:rheinwerk_calibration",
  subject: "human_person:anna",
  consent_ref: "consent:fixture_cpu_face_match",
  scenario: "same-person",   // | different-person | low-quality | spoof
});


client.m13PresenceApproval({
  tenant: "tenant_node:rheinwerk_calibration",
  actor: "human_person:anna",
  vessel: "vessel:fixture_sdk",
  human_presence_receipt: "human_presence_receipt:fixture_private_presence",
  create_standing_from_presence: false,
});


client.m13SessionRevoke({
  tenant: "tenant_node:rheinwerk_calibration",
  session: "auth_session:...",
  enforce_runtime_overlay: true,
});


client.m13KeyRotate({
  tenant: "tenant_node:rheinwerk_calibration",
  key: "key_registry:...",
  replacement_key: "key_registry:...",
  enforce_runtime_overlay: true,
});

See ../api/human-auth.md.

Zeitgestalt

Section titled “Zeitgestalt”
client.zeitgestaltQuery({
  tenant: "tenant_node:rheinwerk_calibration",
  reality: "reality:record",
  question: "why can March not close?",
  entitlement: "entitlement:fixture_zeitgestalt",
});

See ../api/zeitgestalt-and-tensions.md.

Observability and misc

Section titled “Observability and misc”
client.recentCommits();
client.m7State();

See ../api/observability-and-misc.md.

Errors

Section titled “Errors”

The client throws on non-2xx HTTP responses:

try {
  await client.precheckIntent({...});
} catch (e) {
  // network error or HTTP error
  // e.message looks like: "Gestalt membrane call failed: 401"
}

A structural refusal is not an error. It returns a successful MembraneResponse with outcome: "refused". Always inspect outcome before treating a response as success:

const response = await client.precheckIntent({...});


switch (response.outcome) {
  case "admitted":
  case "verified":
  case "executed":
    // success path
    break;
  case "refused":
    // structured refusal; inspect response.body and response.receipt.reasons
    break;
  case "pending":
    // pending action; the act needs higher signing or more evidence
    break;
  case "projected":
    // admitted into a projected reality
    break;
  case "queued":
    // accepted into outbox (effect.intent)
    break;
  case "failed":
    // dispatch attempted but failed (effect.dispatch)
    break;
}

Custom fetch

Section titled “Custom fetch”

The client accepts a fetchImpl option. Use this for:

  • Fixture mode — pass createFixtureFetch() to get canned responses without a server.
  • Tracing — wrap fetch to inject correlation IDs, log timings.
  • Mocking — pass a test double for unit tests.
  • Browser — pass window.fetch.bind(window) if your bundler needs it.
import { GestaltClient, createFixtureFetch } from "@gestalt/sdk";


const client = new GestaltClient({
  baseUrl: "http://fixture",
  fetchImpl: createFixtureFetch(),
});

See fixture-mode.md.

All exported types

Section titled “All exported types”
GestaltRef
MembraneOutcome
GestaltClientOptions
GestaltClient


MembraneReceipt
MembraneResponse<T>
ReceiptVerificationResult


IntentPrecheckRequest
AuthorityResolveContextRequest
ProofRequest
ProofBundleRequest
PackageTrialRequest
RealityForkRequest
RealityCommitRequest
RealityPromoteRequest
RealityDiscardRequest
ZeitgestaltQueryRequest
HumanAuthChallengeRequest
HumanAuthPasskeyVerifyRequest
HumanAuthFaceMatchRequest
M13PresenceApprovalRequest
M13SessionRevokeRequest
M13KeyRotateRequest
EffectIntentRequest
EffectDispatchRequest
EconomicInvoiceRequest
EconomicPaymentObservationRequest
EconomicBookkeepingFactRequest
EconomicPeriodCloseRequest
ConnectorEvidenceIngestRequest
CapabilityPublishRequest
CapabilityPolicyEvaluateRequest


verifyFixtureReceipt(receipt)
createFixtureFetch()
Section titled “Where to read next”