@playaos/api-client 0.58.0 → 0.59.0

package/dist/index.js

@@ -12,6 +12,26 @@ var ApiClientError = class extends Error {
 	}
 };
 /**
+* Error codes a caller may branch on. `ApiClientError.code` stays a plain `string`, since the API
+* can add codes; compare against these constants rather than string literals.
+*/
+const ApiErrorCode = {
+	/** 403: the request writes to an archived event, which is read-only (ADR-128/132). */
+	EVENT_READ_ONLY: "EVENT_READ_ONLY",
+	/** 409: a year-only request matches more than one event; resend with `eventId` (ADR-132). */
+	EVENT_REQUIRED: "EVENT_REQUIRED"
+};
+/** The embed API spells the read-only code in lower_snake; methods that fall back to embed see it. */
+const EMBED_EVENT_READ_ONLY = "event_read_only";
+/**
+* True when a write was refused because its event is archived and read-only: 403 with code
+* `EVENT_READ_ONLY` (or embed's `event_read_only`). Reads of an archived event still succeed. Plain
+* 403 FORBIDDEN (scope or role) is not this error.
+*/
+function isEventReadOnlyError(error) {
+	return error instanceof ApiClientError && error.status === 403 && (error.code === ApiErrorCode.EVENT_READ_ONLY || error.code === EMBED_EVENT_READ_ONLY);
+}
+/**
 * Parse the `Retry-After` header into integer seconds. Only the delta-seconds
 * form is honored; the HTTP-date form is ignored (returns undefined) since
 * callers expect a seconds hint.
@@ -232,24 +252,50 @@ var PlayaOSClient = class PlayaOSClient {
 		book: (token, payload, opts) => post(buildUrl(this.baseUrl, `/public/booking/${encodeURIComponent(token)}/book`), this.auth, payload, opts?.signal),
 		cancel: (token, payload, opts) => post(buildUrl(this.baseUrl, `/public/booking/${encodeURIComponent(token)}/cancel`), this.auth, payload, opts?.signal)
 	};
+	/**
+	* Finance configuration (ADR-129) is scoped by `eventId` or `year` (ADR-132): reads default to the
+	* configured active camp year; `fee_tier`, widget `upsert` and `set_active_tier` write into the scope
+	* sent. Other operations are organization-wide.
+	*/
 	campSettings = {
-		catalog: (opts) => request(buildUrl(this.baseUrl, "/admin/givebutter-catalog"), this.auth, opts?.signal),
+		catalog: (params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return request(buildUrl(this.baseUrl, "/admin/givebutter-catalog", scope), this.auth, opts?.signal ?? signal);
+		},
 		catalogOperation: (payload, opts) => post(buildUrl(this.baseUrl, "/admin/givebutter-catalog"), this.auth, payload, opts?.signal),
-		widgets: (opts) => request(buildUrl(this.baseUrl, "/admin/givebutter-widgets"), this.auth, opts?.signal),
+		widgets: (params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return request(buildUrl(this.baseUrl, "/admin/givebutter-widgets", scope), this.auth, opts?.signal ?? signal);
+		},
 		widgetOperation: (payload, opts) => post(buildUrl(this.baseUrl, "/admin/givebutter-widgets"), this.auth, payload, opts?.signal),
-		admin: (opts) => request(buildUrl(this.baseUrl, "/admin/camp-settings"), this.auth, opts?.signal),
+		admin: (params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return request(buildUrl(this.baseUrl, "/admin/camp-settings", scope), this.auth, opts?.signal ?? signal);
+		},
 		update: (payload, opts) => post(buildUrl(this.baseUrl, "/admin/camp-settings"), this.auth, payload, opts?.signal)
 	};
 	scheduling = {
 		booking: (id, opts) => request(buildUrl(this.baseUrl, `/admin/scheduling/bookings/${encodeURIComponent(id)}`), this.auth, opts?.signal),
 		adminSettings: (opts) => request(buildUrl(this.baseUrl, "/admin/scheduling/settings"), this.auth, opts?.signal),
 		adminOperation: (payload, opts) => post(buildUrl(this.baseUrl, "/admin/scheduling/settings"), this.auth, payload, opts?.signal),
-		feed: (interviewerId, token, opts) => request(buildUrl(this.baseUrl, `/scheduling/feed/${encodeURIComponent(interviewerId)}`, { token }), this.auth, opts?.signal)
+		/**
+		* Calendar subscription read. Scope with `eventId` or `year` (ADR-132); with neither, the
+		* active camp year. A year matching several events fails with 409 EVENT_REQUIRED.
+		*/
+		feed: (interviewerId, token, params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return request(buildUrl(this.baseUrl, `/scheduling/feed/${encodeURIComponent(interviewerId)}`, {
+				token,
+				...scope
+			}), this.auth, opts?.signal ?? signal);
+		}
 	};
 	members = {
+		/** Exports one event, or a year with one event (ADR-132); with neither, the active camp year. */
 		adminExport: (params, opts) => request(buildUrl(this.baseUrl, "/members/admin/export", params), this.auth, opts?.signal),
 		adminOperation: (payload, opts) => post(buildUrl(this.baseUrl, "/members/admin/operation"), this.auth, payload, opts?.signal),
 		adminImportOperation: (payload, opts) => post(buildUrl(this.baseUrl, "/members/admin/import-operation"), this.auth, payload, opts?.signal),
+		/** On an event, `campYear` holds that event's participation (ADR-132). */
 		adminDetail: (id, params, opts) => request(buildUrl(this.baseUrl, `/members/admin/${encodeURIComponent(id)}/detail`, params), this.auth, opts?.signal),
 		adminHistory: (id, opts) => request(buildUrl(this.baseUrl, `/members/admin/${encodeURIComponent(id)}/history`), this.auth, opts?.signal),
 		selfProfile: (params, opts) => request(buildUrl(this.baseUrl, "/members/me/profile", params), this.auth, opts?.signal),
@@ -266,8 +312,14 @@ var PlayaOSClient = class PlayaOSClient {
 		bootstrap: (opts) => request(buildUrl(this.baseUrl, "/members/me/bootstrap"), this.auth, opts?.signal, "no-store"),
 		gates: (opts) => request(buildUrl(this.baseUrl, "/members/me/gates"), this.auth, opts?.signal, "no-store"),
 		dashboard: (opts) => request(buildUrl(this.baseUrl, "/members/me/dashboard"), this.auth, opts?.signal),
-		/** Always the acting member, including admins; requires a member token and members:read scope. */
-		paymentOverview: (opts) => request(buildUrl(this.baseUrl, "/members/me/payment-overview"), this.auth, opts?.signal, "no-store"),
+		/**
+		* Always the acting member, including admins; requires a member token and members:read scope.
+		* Without a scope, the configured active camp year (ADR-132).
+		*/
+		paymentOverview: (params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return request(buildUrl(this.baseUrl, "/members/me/payment-overview", scope), this.auth, opts?.signal ?? signal, "no-store");
+		},
 		/** Acting member's original photo only; missing originals return 404, never an avatar fallback. */
 		selfPhotoDownloadUrl: (opts) => request(buildUrl(this.baseUrl, "/members/me/photo/download-url"), this.auth, opts?.signal, "no-store"),
 		/** Presigned profile-photo upload (PLA-1263). PUT the bytes, then setPhoto. */
@@ -347,13 +399,21 @@ var PlayaOSClient = class PlayaOSClient {
 	dues = { list: (params, opts) => request(buildUrl(this.baseUrl, "/dues", params), this.auth, opts?.signal) };
 	shifts = {
 		memberAction: (payload, opts) => post(buildUrl(this.baseUrl, "/members/shifts/actions"), this.auth, payload, opts?.signal),
+		/** Without a scope, the configured active camp year (ADR-132). */
 		mobile: (params, opts) => request(buildUrl(this.baseUrl, "/members/shifts/mobile", params), this.auth, opts?.signal),
-		memberView: (opts) => request(buildUrl(this.baseUrl, "/members/shifts/view"), this.auth, opts?.signal),
+		/** Without a scope, the configured active camp year (ADR-132). */
+		memberView: (params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return request(buildUrl(this.baseUrl, "/members/shifts/view", scope), this.auth, opts?.signal ?? signal);
+		},
 		adminWorkflow: (payload, opts) => post(buildUrl(this.baseUrl, "/admin/shifts/workflow"), this.auth, payload, opts?.signal),
+		/** Without a scope, the configured active camp year (ADR-132). */
 		planner: (params, opts) => request(buildUrl(this.baseUrl, "/admin/shifts/planner", params), this.auth, opts?.signal),
 		adminOperation: (payload, opts) => post(buildUrl(this.baseUrl, "/admin/shifts/operations"), this.auth, payload, opts?.signal),
 		adminTypes: (opts) => request(buildUrl(this.baseUrl, "/shifts/types"), this.auth, opts?.signal),
+		/** With neither `year` nor `eventId`, every shift in the org (documented ADR-132 exception). */
 		adminList: (params, opts) => request(buildUrl(this.baseUrl, "/shifts/admin", params), this.auth, opts?.signal),
+		/** With neither `year` nor `eventId`, every shift in the org (documented ADR-132 exception). */
 		list: (params, opts) => request(buildUrl(this.baseUrl, "/shifts", params), this.auth, opts?.signal)
 	};
 	org = { get: (opts) => request(buildUrl(this.baseUrl, "/org"), this.auth, opts?.signal) };
@@ -363,7 +423,10 @@ var PlayaOSClient = class PlayaOSClient {
 		adminOperation: (payload, opts) => post(buildUrl(this.baseUrl, "/admin/payments/operations"), this.auth, payload, opts?.signal),
 		unmatchedRefunds: (opts) => request(buildUrl(this.baseUrl, "/admin/payments/unmatched-refunds"), this.auth, opts?.signal),
 		memberPayments: (id, opts) => request(buildUrl(this.baseUrl, `/admin/payments/member/${encodeURIComponent(id)}`), this.auth, opts?.signal),
-		adminSummary: (opts) => request(buildUrl(this.baseUrl, "/admin/payments/summary"), this.auth, opts?.signal),
+		adminSummary: (params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return request(buildUrl(this.baseUrl, "/admin/payments/summary", scope), this.auth, opts?.signal ?? signal);
+		},
 		exportMonarch: (params, opts) => request(buildUrl(this.baseUrl, "/admin/payments/export", params), this.auth, opts?.signal),
 		list: (params, opts) => request(buildUrl(this.baseUrl, "/payments", params), this.auth, opts?.signal),
 		/** Requires a member token. `memberId` may be omitted by a non-admin (defaults to themselves); admins must pass it. */
@@ -376,21 +439,37 @@ var PlayaOSClient = class PlayaOSClient {
 	contacts = { list: (params, opts) => request(buildUrl(this.baseUrl, "/contacts", params), this.auth, opts?.signal) };
 	/** Logistics dashboard reads (PLA-1342): rollup, daily headcount, unsure dates, area breakdowns. */
 	logistics = {
+		/** Requires `eventId` or `year` (ADR-132); an ambiguous year rejects with EVENT_REQUIRED. */
 		summary: (params, opts) => request(buildUrl(this.baseUrl, "/logistics/summary", params), this.auth, opts?.signal),
+		/** Without a scope, the org's active camp year. */
 		headcount: (params, opts) => request(buildUrl(this.baseUrl, "/logistics/headcount", params), this.auth, opts?.signal),
+		/** Without a scope, every camp year. */
 		unsureDates: (params, opts) => request(buildUrl(this.baseUrl, "/logistics/unsure-dates", params), this.auth, opts?.signal),
-		breakdowns: (opts) => request(buildUrl(this.baseUrl, "/logistics/breakdowns"), this.auth, opts?.signal)
+		/** Without a scope, the org's active camp year. */
+		breakdowns: (params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return request(buildUrl(this.baseUrl, "/logistics/breakdowns", scope), this.auth, opts?.signal ?? signal);
+		}
 	};
 	/** Admin reports (PLA-1343): dashboard rollup + build/strike availability. */
 	reports = {
+		/** Requires `eventId` or `year` (ADR-132); an ambiguous year rejects with EVENT_REQUIRED. */
 		dashboard: (params, opts) => request(buildUrl(this.baseUrl, "/reports/dashboard", params), this.auth, opts?.signal),
+		/** Requires `eventId` or `year` (ADR-132); an ambiguous year rejects with EVENT_REQUIRED. */
 		buildStrike: (params, opts) => request(buildUrl(this.baseUrl, "/reports/build-strike", params), this.auth, opts?.signal).then((r) => r.data)
 	};
 	/** Bookkeeping reads (PLA-1345): camp-year list + ops-binder export preview. */
 	bookkeeping = {
-		syncGoogleSheets: (opts) => post(buildUrl(this.baseUrl, "/admin/bookkeeping/sheets/sync"), this.auth, void 0, opts?.signal),
+		/** Without a scope, the camp's active year (ADR-132). */
+		syncGoogleSheets: (params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return post(buildUrl(this.baseUrl, "/admin/bookkeeping/sheets/sync", scope), this.auth, void 0, opts?.signal ?? signal);
+		},
 		adminOperation: (payload, opts) => post(buildUrl(this.baseUrl, "/admin/bookkeeping/operations"), this.auth, payload, opts?.signal),
 		years: (opts) => request(buildUrl(this.baseUrl, "/bookkeeping/years"), this.auth, opts?.signal).then((r) => r.data),
+		/** Requires `eventId` or `year` (ADR-132); an ambiguous year rejects with EVENT_REQUIRED. */
+		summary: (params, opts) => request(buildUrl(this.baseUrl, "/bookkeeping/summary", params), this.auth, opts?.signal),
+		/** Without a scope, the org's operational year. */
 		exportPreview: (params, opts) => request(buildUrl(this.baseUrl, "/bookkeeping/export-preview", params), this.auth, opts?.signal)
 	};
 	/** Operational audit logs (PLA-1338): outbound email sends and inbound webhooks. */
@@ -407,7 +486,9 @@ var PlayaOSClient = class PlayaOSClient {
 		list: (params, opts) => request(buildUrl(this.baseUrl, "/notifications", params), this.auth, opts?.signal)
 	};
 	documents = {
+		/** Scope with `eventId` or `year` (ADR-132); with neither, the active camp year. */
 		memberPage: (params, opts) => request(buildUrl(this.baseUrl, "/members/documents/page", params), this.auth, opts?.signal),
+		/** `eventId` attaches the document to that event (ADR-132); with neither scope, the active camp year. */
 		create: (payload, opts) => post(buildUrl(this.baseUrl, "/documents"), this.auth, payload, opts?.signal),
 		update: (id, payload, opts) => sendV1("PATCH", buildUrl(this.baseUrl, `/documents/${encodeURIComponent(id)}`), this.auth, payload, opts?.signal),
 		delete: (id, opts) => sendV1("DELETE", buildUrl(this.baseUrl, `/documents/${encodeURIComponent(id)}`), this.auth, {}, opts?.signal),
@@ -418,6 +499,7 @@ var PlayaOSClient = class PlayaOSClient {
 		renderContract: (id, opts) => request(buildUrl(this.baseUrl, `/documents/${encodeURIComponent(id)}/render`), this.auth, opts?.signal),
 		signatureDownloadUrl: (id, opts) => request(buildUrl(this.baseUrl, `/documents/signatures/${encodeURIComponent(id)}/download-url`), this.auth, opts?.signal),
 		deleteSignature: (id, opts) => sendV1("DELETE", buildUrl(this.baseUrl, `/documents/signatures/${encodeURIComponent(id)}`), this.auth, {}, opts?.signal),
+		/** With `eventId`, only that event's documents (ADR-132); with no scope, every document. */
 		list: (params, opts) => request(buildUrl(this.baseUrl, "/documents", params), this.auth, opts?.signal),
 		get: (id, opts) => request(buildUrl(this.baseUrl, `/documents/${encodeURIComponent(id)}`), this.auth, opts?.signal),
 		/** Admin member signature rows, optionally filtered to one document. */
@@ -431,6 +513,7 @@ var PlayaOSClient = class PlayaOSClient {
 		/** Save the acting member's response; the date option must belong to this meeting. */
 		rsvp: (id, payload, opts) => sendV1("PUT", buildUrl(this.baseUrl, `/meetings/${encodeURIComponent(id)}/rsvp`), this.auth, payload, opts?.signal),
 		cancelRsvp: (id, opts) => sendV1("DELETE", buildUrl(this.baseUrl, `/meetings/${encodeURIComponent(id)}/rsvp`), this.auth, void 0, opts?.signal),
+		/** With `eventId`, only that event's meetings (ADR-132); with no scope, every meeting. */
 		list: (params, opts) => request(buildUrl(this.baseUrl, "/meetings", params), this.auth, opts?.signal),
 		get: (id, opts) => request(buildUrl(this.baseUrl, `/meetings/${encodeURIComponent(id)}`), this.auth, opts?.signal),
 		/** Create a meeting (PLA-1266). Admin-only; requires a member token. */
@@ -439,10 +522,20 @@ var PlayaOSClient = class PlayaOSClient {
 		archive: (id, opts) => sendV1("DELETE", buildUrl(this.baseUrl, `/meetings/${encodeURIComponent(id)}`), this.auth, void 0, opts?.signal)
 	};
 	scholarships = {
+		/**
+		* Scholarship dashboard for an event or year (ADR-132). A year with one event reads that event;
+		* a year with none reads the annual rows; a year with several fails with 409 `EVENT_REQUIRED`.
+		* With no params, the camp's configured active year (400 when none).
+		*/
 		adminPage: (params, opts) => request(buildUrl(this.baseUrl, "/scholarships/admin-page", params), this.auth, opts?.signal),
 		refresh: (id, opts) => post(buildUrl(this.baseUrl, `/scholarships/${encodeURIComponent(id)}/refresh`), this.auth, {}, opts?.signal),
+		/** Scholarship totals for an event or year; same scope rules and 409 `EVENT_REQUIRED` as `adminPage`. */
 		stats: (params, opts) => request(buildUrl(this.baseUrl, "/scholarships/stats", params), this.auth, opts?.signal),
-		/** Create a scholarship (code + Givebutter sync). Admin-only (PLA-1266). */
+		/**
+		* Create a scholarship (code + Givebutter sync). Admin-only (PLA-1266). A year-only create on a
+		* single-event year writes an event scholarship; an ambiguous year is 409 `EVENT_REQUIRED`
+		* (ADR-132).
+		*/
 		create: (payload, opts) => post(buildUrl(this.baseUrl, "/scholarships"), this.auth, payload, opts?.signal),
 		/** Move a scholarship between assigned/used/expired. Admin-only (PLA-1266). */
 		updateStatus: (id, status, opts) => sendV1("PATCH", buildUrl(this.baseUrl, `/scholarships/${encodeURIComponent(id)}`), this.auth, {
@@ -456,7 +549,17 @@ var PlayaOSClient = class PlayaOSClient {
 	tickets = {
 		/** Admin upsert by member and camp year, including members with no existing tracking row. */
 		upsert: (memberId, year, payload, opts) => sendV1("PUT", buildUrl(this.baseUrl, `/members/${encodeURIComponent(memberId)}/tickets/${year}`), this.auth, payload, opts?.signal),
-		/** Admin ticket-page projection; requires ticket, vehicle-pass, and member read scopes. */
+		/**
+		* Admin upsert for one event (ADR-132). Never creates a participation: a member with none in
+		* the event fails with 404 `PARTICIPATION_NOT_FOUND`. Pass `year` to label an event with no
+		* start date (400 without one); a `year` that disagrees with a dated event is 400.
+		*/
+		upsertForEvent: (memberId, eventId, payload, opts) => sendV1("PUT", buildUrl(this.baseUrl, `/members/${encodeURIComponent(memberId)}/events/${encodeURIComponent(eventId)}/tickets`, { year: opts?.year }), this.auth, payload, opts?.signal),
+		/**
+		* Admin ticket-page projection; requires ticket, vehicle-pass, and member read scopes. Pass
+		* `eventId` for one event's participations; a year with several events fails with
+		* `EVENT_REQUIRED` (ADR-132).
+		*/
 		adminList: (params, opts) => request(buildUrl(this.baseUrl, "/tickets/admin", params), this.auth, opts?.signal),
 		/** Update a member's ticket status/confirmation. Admin-only (PLA-1266). */
 		update: (id, payload, opts) => sendV1("PATCH", buildUrl(this.baseUrl, `/tickets/${encodeURIComponent(id)}`), this.auth, payload, opts?.signal)
@@ -464,35 +567,80 @@ var PlayaOSClient = class PlayaOSClient {
 	vehiclePasses = {
 		/** Admin upsert by member and camp year, including members with no existing tracking row. */
 		upsert: (memberId, year, payload, opts) => sendV1("PUT", buildUrl(this.baseUrl, `/members/${encodeURIComponent(memberId)}/vehicle-passes/${year}`), this.auth, payload, opts?.signal),
+		/**
+		* Admin upsert for one event (ADR-132). Never creates a participation: a member with none in
+		* the event fails with 404 `PARTICIPATION_NOT_FOUND`. Pass `year` to label an event with no
+		* start date (400 without one); a `year` that disagrees with a dated event is 400.
+		*/
+		upsertForEvent: (memberId, eventId, payload, opts) => sendV1("PUT", buildUrl(this.baseUrl, `/members/${encodeURIComponent(memberId)}/events/${encodeURIComponent(eventId)}/vehicle-passes`, { year: opts?.year }), this.auth, payload, opts?.signal),
 		/** Update a member's vehicle-pass status. Admin-only (PLA-1266). */
 		update: (id, payload, opts) => sendV1("PATCH", buildUrl(this.baseUrl, `/vehicle-passes/${encodeURIComponent(id)}`), this.auth, payload, opts?.signal)
 	};
 	shelters = {
 		adminOperation: (payload, opts) => post(buildUrl(this.baseUrl, "/admin/shelters/operations"), this.auth, payload, opts?.signal),
+		/** With an event scope, the acting member and any mates must be confirmed, attending participants. */
 		createForMember: (payload, opts) => post(buildUrl(this.baseUrl, "/members/me/shelters"), this.auth, payload, opts?.signal),
-		updateForMember: (id, payload, opts) => sendV1("PATCH", buildUrl(this.baseUrl, `/members/me/shelters/${encodeURIComponent(id)}`), this.auth, payload, opts?.signal),
-		deleteForMember: (id, opts) => sendV1("DELETE", buildUrl(this.baseUrl, `/members/me/shelters/${encodeURIComponent(id)}`), this.auth, {}, opts?.signal),
+		/** A scope, when sent, must match the shelter's own event; without one, annual shelters only. */
+		updateForMember: (id, payload, params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return sendV1("PATCH", buildUrl(this.baseUrl, `/members/me/shelters/${encodeURIComponent(id)}`, scope), this.auth, payload, opts?.signal ?? signal);
+		},
+		deleteForMember: (id, params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return sendV1("DELETE", buildUrl(this.baseUrl, `/members/me/shelters/${encodeURIComponent(id)}`, scope), this.auth, {}, opts?.signal ?? signal);
+		},
 		memberPage: (params, opts) => request(buildUrl(this.baseUrl, "/members/me/shelters", params), this.auth, opts?.signal),
 		searchMembers: (params, opts) => request(buildUrl(this.baseUrl, "/shelters/member-search", params), this.auth, opts?.signal),
-		requestJoin: (id, opts) => post(buildUrl(this.baseUrl, `/shelters/${encodeURIComponent(id)}/request-join`), this.auth, {}, opts?.signal),
-		inviteCandidates: (id, opts) => request(buildUrl(this.baseUrl, `/shelters/${encodeURIComponent(id)}/invite-candidates`), this.auth, opts?.signal),
+		requestJoin: (id, params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return post(buildUrl(this.baseUrl, `/shelters/${encodeURIComponent(id)}/request-join`, scope), this.auth, {}, opts?.signal ?? signal);
+		},
+		inviteCandidates: (id, params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return request(buildUrl(this.baseUrl, `/shelters/${encodeURIComponent(id)}/invite-candidates`, scope), this.auth, opts?.signal ?? signal);
+		},
 		previewJoinRequest: (token, opts) => request(buildUrl(this.baseUrl, "/shelters/join-requests/preview", { token }), this.auth, opts?.signal),
 		decideJoinRequest: (payload, opts) => post(buildUrl(this.baseUrl, "/shelters/join-requests/decision"), this.auth, payload, opts?.signal),
 		requestPayer: (payload, opts) => post(buildUrl(this.baseUrl, "/shelters/payer-requests"), this.auth, payload, opts?.signal),
 		pendingPayerRequests: (params, opts) => request(buildUrl(this.baseUrl, "/shelters/payer-requests", params), this.auth, opts?.signal),
 		resolvePayerRequests: (payload, opts) => post(buildUrl(this.baseUrl, "/shelters/payer-requests/resolve"), this.auth, payload, opts?.signal),
-		/** Admin-only shelter table/map projection; requires members:read and a member token. */
+		/**
+		* Admin-only shelter table/map projection; requires members:read and a member token. Send
+		* `eventId` or `year` (ADR-132); a year matching several events is 409 EVENT_REQUIRED.
+		*/
 		adminList: (params, opts) => request(buildUrl(this.baseUrl, "/shelters/admin", params), this.auth, opts?.signal),
 		list: (params, opts) => request(buildUrl(this.baseUrl, "/shelters", params), this.auth, opts?.signal),
-		get: (id, opts) => request(buildUrl(this.baseUrl, `/shelters/${encodeURIComponent(id)}`), this.auth, opts?.signal),
-		/** Request to join a shelter (member). PLA-1260. */
-		join: (shelterId, opts) => post(buildUrl(this.baseUrl, `/shelters/${encodeURIComponent(shelterId)}/join`), this.auth, {}, opts?.signal),
-		/** Invite a member to a shelter the acting member owns. PLA-1260. */
-		invite: (shelterId, inviteeUserId, opts) => post(buildUrl(this.baseUrl, `/shelters/${encodeURIComponent(shelterId)}/invites`), this.auth, { inviteeUserId }, opts?.signal),
+		/** Without a scope only annual shelters match; send `eventId` to read an event's shelter. */
+		get: (id, params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return request(buildUrl(this.baseUrl, `/shelters/${encodeURIComponent(id)}`, scope), this.auth, opts?.signal ?? signal);
+		},
+		/** Request to join a shelter (member). PLA-1260. A scope must match the shelter's event. */
+		join: (shelterId, params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return post(buildUrl(this.baseUrl, `/shelters/${encodeURIComponent(shelterId)}/join`, scope), this.auth, {}, opts?.signal ?? signal);
+		},
+		/** Invite a member to a shelter the acting member owns. PLA-1260. A scope must match the shelter's event. */
+		invite: (shelterId, inviteeUserId, params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return post(buildUrl(this.baseUrl, `/shelters/${encodeURIComponent(shelterId)}/invites`), this.auth, {
+				inviteeUserId,
+				...scope
+			}, opts?.signal ?? signal);
+		},
 		/** Leave a shelter (deletes the acting member's own assignment). PLA-1260. */
-		leave: (assignmentId, opts) => sendV1("DELETE", buildUrl(this.baseUrl, `/shelter-assignments/${encodeURIComponent(assignmentId)}`), this.auth, void 0, opts?.signal),
+		leave: (assignmentId, params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return sendV1("DELETE", buildUrl(this.baseUrl, `/shelter-assignments/${encodeURIComponent(assignmentId)}`, scope), this.auth, void 0, opts?.signal ?? signal);
+		},
 		/** Accept or decline a shelter invitation. PLA-1260. */
-		respond: (assignmentId, accept, opts) => sendV1("PUT", buildUrl(this.baseUrl, `/shelter-assignments/${encodeURIComponent(assignmentId)}/response`), this.auth, { accept }, opts?.signal)
+		respond: (assignmentId, accept, params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return sendV1("PUT", buildUrl(this.baseUrl, `/shelter-assignments/${encodeURIComponent(assignmentId)}/response`), this.auth, {
+				accept,
+				...scope
+			}, opts?.signal ?? signal);
+		}
 	};
 	bikes = {
 		adminInterest: (params, opts) => request(buildUrl(this.baseUrl, "/admin/bikes/interest", params), this.auth, opts?.signal),
@@ -610,40 +758,74 @@ var PlayaOSClient = class PlayaOSClient {
 	* Admin/super_admin only; there is no member-facing SAP surface. Year is
 	* the selected year when supplied, otherwise the org's active camp year.
 	*/
+	/** SAP reads and writes take an ADR-132 scope; without one, the configured active camp year. */
 	sap = {
+		/** With an event scope, the event's participants instead of the year's roster. */
 		roster: (params, opts) => request(buildUrl(this.baseUrl, "/sap/roster", params), this.auth, opts?.signal),
 		allocation: {
-			get: (opts) => request(buildUrl(this.baseUrl, "/sap/allocation", { year: opts?.year }), this.auth, opts?.signal),
+			get: (params, opts) => {
+				const { signal, ...scope } = params ?? {};
+				return request(buildUrl(this.baseUrl, "/sap/allocation", scope), this.auth, opts?.signal ?? signal);
+			},
 			update: (payload, opts) => sendV1("PUT", buildUrl(this.baseUrl, "/sap/allocation"), this.auth, payload, opts?.signal)
 		},
 		dayAllocations: {
 			update: (id, payload, opts) => sendV1("PATCH", buildUrl(this.baseUrl, `/sap/day-allocations/${encodeURIComponent(id)}`), this.auth, payload, opts?.signal),
-			remove: (id, opts) => sendV1("DELETE", buildUrl(this.baseUrl, `/sap/day-allocations/${encodeURIComponent(id)}`), this.auth, {}, opts?.signal),
-			list: (opts) => request(buildUrl(this.baseUrl, "/sap/day-allocations", { year: opts?.year }), this.auth, opts?.signal),
-			/** Upserts by (active year, accessDate); 409 on a cross-org date collision. */
+			/** A scope, when sent, must match the row's own event or year. */
+			remove: (id, params, opts) => {
+				const { signal, ...scope } = params ?? {};
+				return sendV1("DELETE", buildUrl(this.baseUrl, `/sap/day-allocations/${encodeURIComponent(id)}`, scope), this.auth, {}, opts?.signal ?? signal);
+			},
+			list: (params, opts) => {
+				const { signal, ...scope } = params ?? {};
+				return request(buildUrl(this.baseUrl, "/sap/day-allocations", scope), this.auth, opts?.signal ?? signal);
+			},
+			/** Upserts by (scope, accessDate); 409 on a date collision or an ambiguous year. */
 			upsert: (payload, opts) => sendV1("PUT", buildUrl(this.baseUrl, "/sap/day-allocations"), this.auth, payload, opts?.signal)
 		},
 		assignments: {
-			list: (opts) => request(buildUrl(this.baseUrl, "/sap/assignments", { year: opts?.year }), this.auth, opts?.signal),
+			list: (params, opts) => {
+				const { signal, ...scope } = params ?? {};
+				return request(buildUrl(this.baseUrl, "/sap/assignments", scope), this.auth, opts?.signal ?? signal);
+			},
 			create: (payload, opts) => post(buildUrl(this.baseUrl, "/sap/assignments"), this.auth, payload, opts?.signal),
 			update: (payload, opts) => sendV1("PATCH", buildUrl(this.baseUrl, "/sap/assignments"), this.auth, payload, opts?.signal),
-			remove: (assignmentId, opts) => sendV1("DELETE", buildUrl(this.baseUrl, "/sap/assignments"), this.auth, { assignmentId }, opts?.signal)
+			remove: (assignmentId, params, opts) => {
+				const { signal, ...scope } = params ?? {};
+				return sendV1("DELETE", buildUrl(this.baseUrl, "/sap/assignments"), this.auth, {
+					assignmentId,
+					...scope
+				}, opts?.signal ?? signal);
+			}
 		}
 	};
 	importantDates = {
-		adminList: (opts) => request(buildUrl(this.baseUrl, "/admin/important-dates"), this.auth, opts?.signal),
+		/** Scope with `eventId` or `year` (ADR-132); with neither, the active camp year (409 when none). */
+		adminList: (params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return request(buildUrl(this.baseUrl, "/admin/important-dates", scope), this.auth, opts?.signal ?? signal);
+		},
 		adminOperation: (payload, opts) => post(buildUrl(this.baseUrl, "/admin/important-dates"), this.auth, payload, opts?.signal),
-		/** Visible camp dates (PLA-1268), optionally pinned to a year. */
+		/** Visible camp dates (PLA-1268), optionally pinned to an event or year (ADR-132). */
 		list: (params, opts) => request(buildUrl(this.baseUrl, "/important-dates", params), this.auth, opts?.signal)
 	};
 	events = { 
 	/** The camp's events with the given status (default `published`), earliest first. */
 list: (params, opts) => request(buildUrl(this.baseUrl, "/events", params), this.auth, opts?.signal) };
 	emails = {
+		/** Payment, attendance and build-week filters follow `eventId` or `year` (ADR-132). */
 		recipients: (payload, opts) => post(buildUrl(this.baseUrl, "/email/recipients"), this.auth, payload, opts?.signal),
+		/** Year-dependent segment counts follow `eventId` or `year`; null when unscoped with no camp year. */
 		composerOptions: (params, opts) => request(buildUrl(this.baseUrl, "/email/composer-options", params), this.auth, opts?.signal),
 		broadcast: (payload, opts) => post(buildUrl(this.baseUrl, "/email/broadcasts"), this.auth, payload, opts?.signal),
-		history: (opts) => request(buildUrl(this.baseUrl, "/email/history"), this.auth, opts?.signal),
+		/**
+		* Broadcast history scoped with `eventId` or `year` (ADR-132); with neither, the configured
+		* active camp year. An event lists its own broadcasts plus the year's camp-wide ones.
+		*/
+		history: (params, opts) => {
+			const { signal, ...scope } = params ?? {};
+			return request(buildUrl(this.baseUrl, "/email/history", scope), this.auth, opts?.signal ?? signal);
+		},
 		deliveryPage: (params, opts) => request(buildUrl(this.baseUrl, "/email/delivery", params), this.auth, opts?.signal),
 		/**
 		* Make one failed retry row due now; the retry executor sends it (nothing is sent by this call).
@@ -718,9 +900,10 @@ list: (params, opts) => request(buildUrl(this.baseUrl, "/events", params), this.
 				return request(buildUrl(this.baseUrl, "/admin/applications", params), this.auth, opts?.signal);
 			},
 			/**
-			* Application capacity for a camp year (PLA-1328): the approved count
-			* against the camp cap, defaulting to the org's active camp year. v1-only
-			* — requires a member token (`withMember`).
+			* Application capacity (PLA-1328): the approved count against the camp
+			* cap for one event, or a year with no event (ADR-132), defaulting to the
+			* org's configured active camp year. v1-only — requires a member token
+			* (`withMember`).
 			*/
 			capacity: (params, opts) => {
 				if (!this.memberToken) throw new Error("applications.capacity requires withMember(token)");
@@ -976,6 +1159,6 @@ function createPublicMarketplaceClient(opts) {
 	};
 }
 //#endregion
-export { ApiClientError, MAX_IMAGE_POSITION, PlayaOSClient, createClient, createPublicMarketplaceClient, exchangeCode };
+export { ApiClientError, ApiErrorCode, MAX_IMAGE_POSITION, PlayaOSClient, createClient, createPublicMarketplaceClient, exchangeCode, isEventReadOnlyError };
 
 //# sourceMappingURL=index.js.map