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({