Guidewire SDK Patterns

Guidewire SDK Patterns

Overview

Build the Cloud API request layer that runs in production. This skill assumes the auth layer from guidewire-install-auth is in place — bearer tokens come from the cached token provider, not a static API_KEY. What this layer adds: safe mutations under optimistic locking, retry-aware writes, quota-friendly request pacing, complete pagination, and a typed error surface that business logic can pattern-match.

Five production failures this skill prevents:

1. 409 Conflict storms — client GETs a record, lets the user (or workflow) edit it, then PATCHes back without the latest checksum; the next concurrent edit causes both PATCHes to lose.
2. 429 cascades — every retry on 429 happens at the same backoff, all clients hammer the endpoint together, the tenant rate quota stays pinned.
3. Silent data loss in pagination — client treats pageSize=100 as "all results"; misses page 2 onward; reports inflated coverage to downstream.
4. Duplicate writes on retry — POST to create-claim times out at the load balancer, client retries, two claims land with the same FNOL.
5. Generic error handling — every non-2xx response collapses into "request failed", losing the userMessage, errors[].type, and attributes structure the API actually returns.

Prerequisites

• A working auth layer per guidewire-install-auth — getToken() returning a cached, scope-validated bearer
• Cloud API endpoints reachable on [TENANT].guidewire.net (PC/CC/BC base URLs in env)
• Node 20+ or equivalent runtime supporting fetch, AbortController, and crypto.randomUUID
• Familiarity with the Cloud API response envelope (data[], attributes, checksum, links) — see guidewire-install-auth/references/API_REFERENCE.md

Instructions

Implement the patterns below as composable layers on top of fetch. Each pattern targets one of the five production failures listed in Overview; do not skip any layer in production code.

1. Checksum round-trip for safe mutations

Every Cloud API resource carries a checksum. PATCH and PUT must echo the latest checksum in the request body, or the API returns 409 Conflict to protect concurrent writers. Wrap mutations in a fetch-then-mutate helper that does the round-trip automatically.

export async function patchResource<T>(path: string, mutate: (current: T) => Partial<T>): Promise<T> {
  const token = await getToken();
  const getRes = await fetch(`${BASE}${path}`, { headers: { Authorization: `Bearer ${token}` } });
  if (!getRes.ok) throw await mapError(getRes, "GET", path);
  const { data: current } = await getRes.json();

  const patchRes = await fetch(`${BASE}${path}`, {
    method: "PATCH",
    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      data: { attributes: mutate(current.attributes), checksum: current.checksum },
    }),
  });
  if (!patchRes.ok) throw await mapError(patchRes, "PATCH", path);
  return (await patchRes.json()).data;
}

When 409 still occurs (rare race), the caller should retry the helper itself, not the inner PATCH — the inner PATCH would just hit 409 again with the same stale checksum.

2. Retry-After-aware rate limiting

On 429 Too Many Requests, Cloud API returns a Retry-After header that is either an integer (seconds) or an HTTP date. Honour both forms; never use a fixed backoff. Combine with exponential-with-jitter for transient 5xx so concurrent clients do not synchronize their retries.

async function backoffFor(res: Response, attempt: number): Promise<number> {
  if (res.status === 429) {
    const ra = res.headers.get("Retry-After");
    if (ra) return /^\d+$/.test(ra) ? Number(ra) * 1000 : Math.max(0, Date.parse(ra) - Date.now());
  }
  // Decorrelated jitter: caps the herd, keeps p99 sane
  return Math.min(30_000, Math.random() * (200 * 2 ** attempt));
}

3. Pagination via offsetToken

Cloud API does not page by number. The response carries links.next.href until the data is exhausted; absence of links.next is the terminator. Iterate as a generator so callers do not buffer the whole dataset.

export async function* paginate<T>(path: string): AsyncGenerator<T> {
  let next: string | null = path;
  while (next) {
    const token = await getToken();
    const res = await fetch(`${BASE}${next}`, { headers: { Authorization: `Bearer ${token}` } });
    if (!res.ok) throw await mapError(res, "GET", next);
    const body = await res.json();
    for (const item of body.data) yield item.attributes as T;
    next = body.links?.next?.href ?? null;
  }
}

4. Idempotency-Key for retry-safe writes

POST is not naturally idempotent. A timeout at the load balancer can cause the client to retry a request the API already processed — duplicate claim, duplicate payment, duplicate activity. Cloud API accepts an Idempotency-Key header; supplied keys deduplicate within a 24-hour window. Generate a v4 UUID per logical operation (not per HTTP attempt).

export async function createClaim(payload: NewClaim): Promise<Claim> {
  const idempotencyKey = crypto.randomUUID(); // generated once, reused across retries
  return retryable(async () => {
    const token = await getToken();
    const res = await fetch(`${BASE}/cc/rest/v1/claims`, {
      method: "POST",
      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey },
      body: JSON.stringify({ data: { attributes: payload } }),
    });
    if (!res.ok) throw await mapError(res, "POST", "/cc/rest/v1/claims");
    return (await res.json()).data;
  });
}

5. Structured error mapping

Cloud API error bodies are structured: { userMessage, errors: [{ message, type, attributes }] }. Lift the structure into a typed exception so business logic can pattern-match (if (e instanceof GwBusinessRuleError) rather than if (msg.includes("policy"))).

export class GwError extends Error {
  constructor(public status: number, public op: string, public path: string,
              public body: { userMessage?: string; errors?: { type?: string; message: string; attributes?: unknown }[] }) {
    super(body.userMessage ?? `${op} ${path} failed: ${status}`);
  }
  is(type: string): boolean { return !!this.body.errors?.some(e => e.type === type); }
}

async function mapError(res: Response, op: string, path: string): Promise<GwError> {
  const body = await res.json().catch(() => ({}));
  return new GwError(res.status, op, path, body);
}

Output

A production-grade Cloud API client ships with all five layers wired:

• patchResource(path, mutate) and putResource(path, replace) helpers performing checksum round-trip — callers never touch raw checksum fields.
• A retryable(fn) wrapper using backoffFor() to honour Retry-After and apply jitter on transient 5xx.
• paginate(path) async generator yielding all records without buffering; callers iterate naturally.
• Idempotency-Key set on every POST, with the key generated once per logical operation and persisted across retries.
• GwError exceptions exposing .status, .op, .path, structured .body, and .is(type) for pattern matching.