@sekiban/cloud-client

Credentialed Sekiban Cloud transport for Serialized DCB V1. This package is the TypeScript twin of Sekiban.Cloud.Client in this repository.

License: MIT for this package. Dependencies @sekiban/dcb-* are Elastic-2.0.

Install (local pack)

Registry publication is operator-gated. Until @sekiban/cloud-client is published, install from a local pack:

npm pack
npm install ./sekiban-cloud-client-0.2.0.tgz

Configuration (four keys)

| Key | Purpose | | --- | --- | | BaseUrl | Sekiban Cloud runtime base URL | | ServiceId | Tenant service id (path segment and header) | | CredentialId | X-Sekiban-Credential-Id | | CredentialSecret | X-Sekiban-Credential-Secret (never logged) |

All four keys must be non-empty. Whitespace-only values fail fast at factory construction with zero HTTP.

Scoped URL formula

Every operation POSTs to:

${trimTrailingSlash(BaseUrl)}/api/${ServiceId}/sekiban/serialized/${operation}

Operations: commit, tag-state, tag-latest-sortable, query, list-query.

Unscoped /api/sekiban/serialized/* paths are never used by this package.

Credential headers (three)

Every request sends:

• X-Sekiban-Service-Id — same value as the path ServiceId
• X-Sekiban-Credential-Id
• X-Sekiban-Credential-Secret
• content-type: application/json

Usage with createSekibanExecutor

import { createSekibanExecutor } from "@sekiban/dcb-client";
import { createSekibanCloudTransport } from "@sekiban/cloud-client";

const transport = createSekibanCloudTransport({
  BaseUrl: process.env.SEKIBAN_CLOUD_BASE_URL!,
  ServiceId: process.env.SEKIBAN_CLOUD_SERVICE_ID!,
  CredentialId: process.env.SEKIBAN_CLOUD_CREDENTIAL_ID!,
  CredentialSecret: process.env.SEKIBAN_CLOUD_CREDENTIAL_SECRET!,
});

const executor = createSekibanExecutor(transport, {
  serviceId: process.env.SEKIBAN_CLOUD_SERVICE_ID!,
});

const result = await executor.execute(async (ctx) => {
  ctx.append("MyEvent", { value: 1 }, ["g/my-aggregate"]);
  return { kind: "committed" };
});

Fail-closed consistency: "safe"

Azure serialized list-query has no safe lane yet. When listQuery queryParamsJson is a JSON object embedding "consistency":"safe" (including after the executor copies ListQueryOptions.consistency), the transport throws ClientError("unsupported_consistency_mode") with zero HTTP. Safe is never forwarded silently.

"unsafe" may be forwarded for adapter completeness; it is not documented as production-ready.

Abort and timeout codes

• AbortError (name === "AbortError") → code aborted (executor kind timeout on execute paths)
• TimeoutError (name === "TimeoutError") → ClientError("timeout")

These are not collapsed into generic transport.

No retry

The client never retries. Callers own recovery.

npm publish

Pack-ready via npm pack / CI. Registry publication is GitHub Actions + Trusted Publishing (OIDC) only (.github/workflows/release-cloud-client.yml). NPM_TOKEN is not the operating path. Local npm publish is allowed only as a one-shot bootstrap so the package exists and a Trusted Publisher can be registered on npm; afterward every release is OIDC via Actions.

See docs/developer-guide/cloud-client-npm-release.md.