WalkPic documentation

TypeScript SDK

A typed HTTP client with explicit credentials and cancellation.

import {createWalkPicClient, CredentialSession} from '@walkpic/sdk';
const credentials = new CredentialSession({bearer: accessToken});
const client = createWalkPicClient({baseUrl: 'https://walkpic.com', credentials});
try {
  const result = await client.execute('integrationListOwnedPublications', {query:{limit:'5'}});
  // Inspect the typed status and use approved data in your application.
} finally { client.close(); credentials.close(); }

Detailed usage

WalkPic SDK 0.1.0

A direct HTTP client for Node 24.21.0. All 203 operation wrappers and DTOs derive from the versioned WalkPic contract. The packed runtime and declarations are self-contained; consumers need no TypeScript loader, service source or room key.

import {createWalkPicClient, CredentialSession, integrationListOwnedPublications} from '@walkpic/sdk';
const credentials = new CredentialSession({bearer: accessToken});
const client = createWalkPicClient({baseUrl: 'https://walkpic.com', credentials});
try {
  const result = await integrationListOwnedPublications(client.transport, {signal: controller.signal});
  if (result.status === 200) {
    const publications = result.body.items; // use approved data in your application
  }
  else console.error(result.status); // declared errors are typed response values
} finally {
  client.close();
  credentials.close();
}

client.execute(operationId, input) has the same generated types. client.executeUnknown(operationId, input) validates unknown CLI/MCP input before sending it. validateUnknownRequest(operationId, input) returns issue arrays without HTTP or credential side effects. getOperationSchema(operationId) returns frozen public operation/components metadata for adapters. operationDefinitions and operationTransportDefinitions describe methods, paths, representations and path encodings. Neither metadata nor integration-policy candidate status grants permission; the server enforces current authorization, scopes and domain access.

The eight integration* reads use generated /v2 paths and the mandatory IntegrationBearer scheme. Original /v1 operations remain separate. The SDK never rewrites paths or treats the operation-policy catalog as authorization.

Credentials are explicit. CredentialSession stores only the provided opaque bearer, integrationRefresh, deletionReceipt, publicationLink, and/or liveWriter values in memory. It performs no automatic login, refresh, token decoding, grant issuance or persistence. rotate(next) aborts requests and streams using the old account/credential lease; close() aborts and clears them. A custom CredentialProvider.resolve(context) returns {credentials, signal?, revision?}. Its host owns secure storage and aborts its lease on account change/revocation. Session and deletion credentials cannot both occupy Authorization. Capability headers cannot override provider values. Credentials are attached only to security schemes declared by the operation. Redirects are returned without following them or forwarding credentials.

Approve a personal read grant at https://app.walkpic.com/integrations. The live page names the client, selected reads and lifetime, reveals credentials once, and supports revocation. Use https://walkpic.com as the public API base. Production acceptance verified all eight scoped reads through SDK, CLI and MCP, explicit private-channel refresh, revocation and current actor access loss with an owned QA account. See docs/evidence/resumed-delivery-20261005/integration-acceptance/public-verification-r4.json. This acceptance does not establish Apple/email sign-in or photographic resource ACL acceptance, which have separate evidence.

Explicit refresh uses the generated integrationRefreshPersonalGrant operation with {body: {requestId, clientId, grantId}} and a separate CredentialSession({integrationRefresh: refreshToken}). That credential is sent solely to the IntegrationRefresh security scheme, never to read operations. Refresh cannot extend approved scopes or the grant expiry. The host must accept the complete validated pair through its trusted credential channel and rotate or restart read clients. A lost acknowledgement cannot recover plaintext; do not retry the refresh automatically. The CLI provides an explicit private pipe handoff; MCP exposes no credential-management tools.

import {planningOpenChangeEvents, changeEvents} from '@walkpic/sdk';
const response = await planningOpenChangeEvents(client.transport, {query: {liveId: [liveId]}, signal});
if (response.status === 200) {
  for await (const {event} of changeEvents(response.body)) {
    // Invalidate and reread the appropriate authorized endpoint.
    // Every observed frame has an empty data object.
  }
}

Streams are pull-driven, validate complete frames after incremental UTF8 decoding, and remain bounded. Breaking an iterator, explicit body.cancel(), caller abort, credential rotation or client close cancels the reader and clears owned resources. There is no automatic reconnection, Last-Event-ID replay, mutation retry or refresh. An ordinary clean stream close can mean access loss; reauthentication belongs to the host. Caller AbortSignal reasons are preserved; provider/network/stream errors become content-free WalkPicSdkError values. Do not print credential inputs or protected response payloads in adapter diagnostics.

The default finite deadline is 60 seconds, including credential resolution and body reads. SSE uses that handshake deadline, then a 60-second deadline for each held upstream read, without a total-duration cap. Limits are configurable positive integers through limits: requestBytes 8 MB, jsonBytes/textBytes 8 MB, binaryBytes 32 MB, frameBytes 4096, chunkBytes 1 MiB, streamIdleTimeoutMs 60 seconds. These are client resource limits in addition to server limits. JSON inputs are plain data, bounded before serialization (depth256), with no custom toJSON/functions/cycles. Bytes are checked before copying. Query strings preserve source lexical values; exploded arrays retain repeated keys. Static suffix paths preserve nested separators; dot/empty segments are rejected as unrepresentable destinations. Headers and media are contract-bound.

JSON, text, bytes, HEAD and declared empty responses are distinguished. Files marked binary remain bytes even with JSON/JavaScript MIME. Responses, including finite errors, are checked before exposing their bodies. Fetch-decoded compressed responses are bounded/validated, but encoded Content-Length is not compared with decoded bytes. Request validation defers only server-clock relative timing; date parsing and all other structural/static constraints remain mandatory, and the server still enforces time, permission, replay and current-state rules.

The Node entry does not implement the cookie/CSRF web broker adapter. The explicit browser guest entry is documented below. Direct base URLs must be HTTPS origins; HTTP is allowed only for literal loopback hosts in tests/local tools. No direct database access or permission bypass is available. Bundled third-party licenses and hashes are in dist/LICENSES.json.

From the repository: npm ci --prefix packages/sdk, then npm run test --prefix packages/sdk, npm run build --prefix packages/sdk, and npm pack --prefix packages/sdk. Typecheck rejects maintained JavaScript, including nested source/build/test code, with only package-root dist/.package/.declarations/node_modules exempt. Build uses the pinned contract source and emits the declaration closure; the tarball can be installed independently. Registry publication and hosted production delivery are separate integrating-agent steps.

The explicit @walkpic/sdk/browser-guest entry supports six existing guest operations: publication detail, photo bytes, published-story speech, public reports, public configuration and MapKit token retrieval. It shares the Node serializer, transport, generated DTOs, cancellation and annotation validation. Schema shapes are compiled at build time; the browser bundle includes neither Ajv's runtime compiler nor Node polyfills and works with script-src 'self' without unsafe-eval.

import {createWalkPicGuestClient, GuestCredentialSession,
  contentReadPublication} from '@walkpic/sdk/browser-guest';
const guestCredentials = new GuestCredentialSession({publicationLink: token});
const guest = createWalkPicGuestClient({baseUrl: apiOrigin, credentials: guestCredentials});
try {
  const result = await contentReadPublication(guest.transport, {path: {publicationId}, signal});
  if (result.status === 200) renderAuthorizedPublication(result.body);
} finally { guest.close(); guestCredentials.close(); }

The origin defaults to location.origin; an explicit HTTPS API origin is allowed (loopback HTTP is available for local fixtures). Fetch uses credentials: 'omit', cache: 'no-store', referrerPolicy: 'no-referrer' and manual redirects. Browser controlled Origin remains automatic. Capability input belongs to the memory provider, never query strings or manual capability headers; bearer, deletion, refresh and live-writer credentials are rejected. Typed execute and executeUnknown accept only the six guest IDs. The generated-wrapper-compatible transport rejects any other ID before credentials or network work.

Guest defaults are a 20-second deadline, 3,000,000 JSON response bytes, 15 MiB binary response bytes and 8192 request bytes; timeoutMs and limits are explicit positive bounded overrides. The host sets the existing 50-second speech deadline when needed. Cross-origin requests require approved service CORS and observable media headers. The guest photo profile requires observable Accept-Ranges on 200/206 and Content-Range on206/416. Successful JPEG reads also require standard Content-Length or the declared X-WalkPic-Media-Length. The application header counts decoded JPEG bytes, survives gateway reframing and is validated as a positive safe integer no greater than15MiB; it must exactly match the bounded decoded payload. Shared schemas retain standard Content-Length validation; 206 decoded bytes must match the exact range. The additional response header is optional in the versioned contract and does not change access or capabilities. Validators never infer hidden headers. Cross-origin Fetch can hide Content-Encoding, so an unknown encoded Content-Length is not compared with decoded bytes. Schema/header checks and decoded-byte resource bounds still apply, while observable identity encoding keeps the original comparison. A custom Fetch port is trusted host code and must preserve these policies and transparent responses. Viewer resource/epoch cleanup remains the host's responsibility.

dist/browser-manifest.json binds the six-operation schema closure to its source contract and runtime hash. dist/BROWSER_LICENSES.json records the browser runtime metafile and inlined ajv-formats generator notice closure; ship those notices together with dist/LICENSES.json and dist/licenses. The six-operation browser guest entry is used by the deployed TypeScript public viewer. Owned production Chrome/WebKit acceptance verifies the scoped viewer journeys; it does not establish all-operation browser support, installed Safari or physical-device acceptance.