Guidewire Sdk PatternsSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: guidewire-sdk-patterns
description: Build a production-grade Guidewire Cloud API client that survives the request-side failures — 409 checksum conflicts on PATCH/PUT, 429 quota throttling, offsetToken pagination drift, retry-unsafe POSTs, and unstructured error responses. Use when designing an HTTP client wrapper around PolicyCenter, ClaimCenter, or BillingCenter REST endpoints. Trigger with "guidewire client", "guidewire sdk", "checksum 409", "guidewire pagination", "guidewire rate limit", "Retry-After".
allowed-tools: Read, Write, Edit, Bash(curl:*), Bash(jq:*), Grep
version: 1.26.0
license: MIT
author: Jeremy Longshore <[email protected]>
compatibility: Designed for Claude Code
tags:
  - guidewire
  - rest-client
  - retry
  - idempotency
  - rate-limiting
  - pagination
---

# 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.

```typescript
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.

```typescript
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.

```typescript
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).

```typescript
export async function createClaim(payload: NewClaim): Promise<Claim> {
  const idempotencyKey = crypto.

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.