@playaos/api-client 0.57.0 → 0.59.0

package/dist/index.d.ts

@@ -16,6 +16,29 @@ export declare class ApiClientError extends Error {
    */
   retryAfter?: number | undefined);
 }
+/**
+ * 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.
+ */
+export declare const ApiErrorCode: {
+  /** 403: the request writes to an archived event, which is read-only (ADR-128/132). */
+  readonly EVENT_READ_ONLY: "EVENT_READ_ONLY";
+  /** 409: a year-only request matches more than one event; resend with `eventId` (ADR-132). */
+  readonly EVENT_REQUIRED: "EVENT_REQUIRED";
+};
+/** The embed API spells the read-only code in lower_snake; methods that fall back to embed see it. */
+declare const EMBED_EVENT_READ_ONLY = "event_read_only";
+/** An `ApiClientError` that `isEventReadOnlyError` accepted: a 403 with either read-only spelling. */
+type EventReadOnlyApiError = ApiClientError & {
+  readonly status: 403;
+  readonly code: typeof ApiErrorCode.EVENT_READ_ONLY | typeof EMBED_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.
+ */
+export declare function isEventReadOnlyError(error: unknown): error is EventReadOnlyApiError;
 //#endregion
 //#region src/types.d.ts
 /** Cursor-paginated list envelope returned by v1 list endpoints (PLA-779). */
@@ -35,6 +58,23 @@ type PaginationParams = {
   /** Opaque cursor from a previous response's nextCursor. */
   cursor?: string;
 };
+/**
+ * Event scope for event-scoped reads and writes (ADR-132). Send `eventId` for a canonical event.
+ * Year handling is endpoint-specific during the ADR-132 rollout (`playa-0i3qp.11.3.x`): endpoints
+ * that have adopted the contract resolve a `year` alone to at most one event and answer
+ * 409 `EVENT_REQUIRED` with the candidate events when it matches several; endpoints that have
+ * not adopted it yet still treat `year` as the legacy annual filter.
+ *
+ * Shifts have adopted it: `shifts.list`, `adminList`, `planner`, `mobile`, `memberView`, the date-keyed
+ * `adminOperation` actions and the `adminWorkflow` publish action. `shifts.list` and `shifts.adminList`
+ * with neither field keep the org-wide read (documented exception).
+ */
+type EventScopeParams = {
+  /** Legacy camp year. */
+  year?: number;
+  /** Canonical event ID. */
+  eventId?: string;
+};
 interface Member {
   id: string;
   firstName: string;
@@ -123,7 +163,29 @@ interface ApplicationCapacity {
   limit: number;
   atCapacity: boolean;
 }
+interface ApplicationWorkflowCapabilities {
+  transitions: {
+    to: "approved" | "rejected" | "waitlisted" | "interviewed";
+    enabled: boolean;
+    reason?: string;
+  }[];
+  invite: {
+    enabled: boolean;
+    reason?: string;
+  };
+  interviewNote: {
+    enabled: boolean;
+    reason?: string;
+  };
+  annotations: {
+    notes: boolean;
+    tags: boolean;
+    scores: boolean;
+  };
+}
 interface ApplicationAdmin extends Application {
+  /** Advisory server policy; writes remain authoritative. Absent on older servers. */
+  workflowCapabilities?: ApplicationWorkflowCapabilities;
   /** Applicant phone from the joined profile (PLA-1322). */
   phone: string | null;
   /** Applicant birthday (YYYY-MM-DD) from the joined profile (PLA-1332). */
@@ -173,6 +235,17 @@ interface ImportantDate {
   endDate: string | null;
   category: string | null;
   year: number;
+  /** Canonical event the date belongs to (ADR-132); null for an annual camp date. */
+  eventId?: string | null;
+}
+type EventStatus = "draft" | "published" | "archived";
+interface EventSummary {
+  id: string;
+  name: string;
+  status: EventStatus;
+  startDate: string | null;
+  endDate: string | null;
+  timezone: string | null;
 }
 interface SummerCampAttendee {
   profileId: string;
@@ -186,6 +259,8 @@ interface SummerCampAttendee {
 }
 interface SheetsSyncResult {
   year: number;
+  /** The event exported, or null when a camp year was exported (ADR-132). */
+  eventId: string | null;
   tabs: {
     name: string;
     rows: number;
@@ -288,8 +363,9 @@ interface PhotoExportJob {
   completedAt: string | null;
 }
 interface CreatePhotoExportInput {
+  /** Canonical event (`events.id`) to export. Required since 0.58.0, which removed `year`. */
+  eventId: string;
   attending?: "true" | "all";
-  year?: number;
   role?: string;
   status?: string;
   search?: string;
@@ -300,7 +376,8 @@ interface OnboardingProgress {
   orgId: string;
   userId: string;
   itemId: string;
-  year: number;
+  eventId: string | null;
+  year: number | null;
   completed: boolean | null;
 }
 /** A camp year with its per-year member/date counts (`GET /bookkeeping/years`, PLA-1345). */
@@ -319,13 +396,31 @@ interface CampYearWithCounts {
 /** Ops-binder export preview counts (`GET /bookkeeping/export-preview`, PLA-1345). */
 interface BookkeepingExportPreview {
   year: number | null;
+  /** The event counted, or null on the annual path (ADR-132). */
+  eventId: string | null;
   memberCount: number;
   menuCount: number;
   shelterCount: number;
 }
+/** Financial rollup for an event or camp year (`GET /bookkeeping/summary`). Money fields are decimal strings. */
+interface BookkeepingSummary {
+  year: number;
+  /** The event read, or null on the annual path (ADR-132). */
+  eventId: string | null;
+  revenue: string;
+  paymentCount: number;
+  budgetTotal: string;
+  budgetSpent: string;
+  vendorPaid: string;
+  vendorOutstanding: string;
+  vendorCount: number;
+  memberCount: number;
+}
 /** Admin dashboard rollup (`GET /reports/dashboard`). */
 interface DashboardMetrics {
   year: number;
+  /** The event read, or null on the annual path (ADR-132). */
+  eventId: string | null;
   asOf: string;
   totalHeadcount: number;
   memberCount: number;
@@ -358,6 +453,8 @@ interface BuildStrikeReportRow {
 /** Logistics dashboard rollup (`GET /logistics/summary`, PLA-1342). */
 interface LogisticsSummary {
   year: number;
+  /** The event read, or null on the annual path (ADR-132). */
+  eventId: string | null;
   buildWeekCount: number;
   confirmedBuildWeek: number;
   strikeCrewCount: number;
@@ -415,6 +512,8 @@ interface TshirtSizeTotal {
 }
 /** The three logistics breakdown views, bundled (`GET /logistics/breakdowns`). */
 interface LogisticsBreakdowns {
+  /** The event read, or null on the annual path (ADR-132). */
+  eventId: string | null;
   rvAmperage: RvAmperageTotal[];
   shelterTypes: ShelterTypeDistribution[];
   tshirtSizes: TshirtSizeTotal[];
@@ -444,7 +543,8 @@ interface MemberCustomChecklistItem {
   categoryId: string;
   name: string;
   completed: boolean | null;
-  year: number;
+  eventId: string | null;
+  year: number | null;
 }
 interface DuesStatus {
   userId: string | null;
@@ -453,6 +553,8 @@ interface DuesStatus {
   amountOwed: string | null;
   amountPaid: string | null;
   balance: string | null;
+  /** Event the row is for; absent on the annual path (ADR-132). */
+  eventId?: string | null;
 }
 /** Per-member dues state from `member_dues_status` (PLA-1336). */
 interface MemberDuesStatus {
@@ -471,6 +573,10 @@ interface MemberDuesStatus {
   attendanceResponse: string | null;
   /** Whether the member has ever signed in (PLA-1343). */
   hasLoggedIn: boolean | null;
+  /** Event the row is for; absent or null on the annual path (ADR-132). */
+  eventId?: string | null;
+  /** Event participation status; absent or null on the annual path. */
+  participationStatus?: string | null;
 }
 /** Per-tier dues totals from `dues_summary` (PLA-1336). */
 interface DuesSummaryRow {
@@ -520,6 +626,8 @@ interface ShiftSignup {
   userId: string;
   status: string | null;
   role: string | null;
+  canceledAt?: string | null;
+  waitlistedAt?: string | null;
 }
 interface ShiftType {
   id: string;
@@ -527,10 +635,16 @@ interface ShiftType {
   description: string | null;
 }
 interface Shift {
+  /** Server-owned self-service time window only; publication and capacity are separate. */
+  selfServiceOpen?: boolean;
+  /** Effective capacity for self-service signup; independent of mobile/admin policies. */
+  selfSignupCapacity?: number;
   id: string;
   orgId: string;
   shiftDate: string;
   year: number;
+  /** Canonical event the shift belongs to; null on the annual (untagged) calendar (ADR-132). */
+  eventId: string | null;
   startTime: string | null;
   endTime: string | null;
   maxSlots: number | null;
@@ -560,7 +674,10 @@ interface AdminShiftType extends ShiftType {
 interface AdminShelter {
   id: string;
   orgId: string;
+  /** Camp-year label; event shelters carry the resolved event's year. */
   year: number;
+  /** Event the shelter belongs to; null for an annual shelter. */
+  eventId: string | null;
   name: string | null;
   shelterType: string;
   ownerUserId: string | null;
@@ -588,8 +705,28 @@ interface AdminShelter {
     } | null;
   }>;
 }
+/** An organization-owned event, as listed on `GET /org` (ADR-132). */
+interface OrgEvent {
+  id: string;
+  name: string;
+  slug: string;
+  status: "draft" | "published" | "archived";
+  startDate: string | null;
+  endDate: string | null;
+}
 interface OrgConfig {
+  /** Canonical branding fields; absent on older API deployments. */
+  tagline?: string | null;
+  description?: string | null;
+  /**
+   * @deprecated Display and legacy use only: the configured active camp year, else the current
+   * calendar year. Not an event scope (ADR-132); send `eventId` or an explicit `year` instead.
+   */
   activeCampYear: number;
+  /** Actual configured active camp year; absent on older API deployments. Never a calendar fallback. */
+  configuredActiveCampYear?: number | null;
+  /** The organization's events, ordered by start date; absent on older API deployments (ADR-132). */
+  events?: OrgEvent[];
   id: string;
   name: string;
   slug: string;
@@ -670,6 +807,8 @@ interface CampDocument {
   isActive: boolean | null;
   requiresEsignature: boolean | null;
   year: number;
+  /** Canonical event the document belongs to (ADR-132); null for an annual camp document. */
+  eventId?: string | null;
   publishedAt: string | null;
   createdAt: string | null;
   updatedAt: string | null;
@@ -704,7 +843,10 @@ interface Shelter {
   name: string | null;
   shelterType: string;
   ownerUserId: string | null;
+  /** Camp-year label; event shelters carry the resolved event's year. */
   year: number;
+  /** Event the shelter belongs to; null for an annual shelter. */
+  eventId: string | null;
   maxOccupants: number | null;
   rvLengthFt: number | null;
   rvAmperage: number | null;
@@ -821,6 +963,13 @@ interface MemberGroupRosterRow {
   profileStatus: string | null;
 }
 interface ApplicationCreatePayload {
+  /** Stable opaque UUID for exact-payload receipt recovery; never reuse for changed answers. */
+  submission_id?: string;
+  /**
+   * The event to apply to. Required only when the active camp year has several events: the server
+   * answers 409 EVENT_REQUIRED with the candidates, and the retry sends one of them (ADR-132).
+   */
+  event_id?: string;
   acknowledged_expectations?: true;
   first_name: string;
   last_name: string;
@@ -849,6 +998,10 @@ interface ApplicationCreatePayload {
 interface ApplicationCreateResponse {
   applicationId: string;
   status: string;
+  /** Original accepted camp year. */
+  year?: number;
+  /** Present for opted-in submissions; only false authorizes fresh delivery side effects. */
+  replayed?: boolean;
 }
 interface ApplicationTransitionPayload {
   to: ApplicationStatus;
@@ -963,6 +1116,12 @@ interface DuesCreatePayload {
   amount: number;
   paymentMethod?: string;
   duesCollectionId?: string;
+  /**
+   * ADR-132: only checks that `duesCollectionId` belongs to this event (or to `year` with no
+   * event). Both transports read this spelling.
+   */
+  eventId?: string;
+  year?: number;
 }
 interface DuesCreateResponse {
   paymentId: string;
@@ -1155,27 +1314,30 @@ interface UpsertPackingCampItemInput {
   notes?: string | null;
   sortOrder?: number;
 }
-/** Active-year allocation summary. Year is always the org's active camp year. */
+/**
+ * Allocation summary for one scope (ADR-132). `year` is the camp-year label; `eventId` is the event
+ * the rows belong to, or null on the legacy annual path.
+ */
 interface SapAllocation {
   year: number;
+  eventId: string | null;
   totalAllocated: number;
   notes: string | null;
   totalAssigned: number;
 }
-interface UpdateSapAllocationInput {
-  year?: number;
+interface UpdateSapAllocationInput extends EventScopeParams {
   totalAllocated: number;
   notes?: string | null;
 }
 interface SapDayAllocation {
   id: string;
   year: number;
+  eventId: string | null;
   accessDate: string;
   slotsAvailable: number;
   notes: string | null;
 }
-interface UpsertSapDayAllocationInput {
-  year?: number;
+interface UpsertSapDayAllocationInput extends EventScopeParams {
   accessDate: string;
   slotsAvailable: number;
   notes?: string | null;
@@ -1184,14 +1346,15 @@ interface SapAssignment {
   id: string;
   userId: string;
   year: number;
+  eventId: string | null;
   sapNumber: string | null;
   vehicleDescription: string | null;
   licensePlate: string | null;
   arrivalDate: string | null;
   notes: string | null;
 }
-interface CreateSapAssignmentInput {
-  year?: number;
+/** With an event scope, `userId` must be a participant of that event. */
+interface CreateSapAssignmentInput extends EventScopeParams {
   userId: string;
   sapNumber?: string | null;
   vehicleDescription?: string | null;
@@ -1199,7 +1362,8 @@ interface CreateSapAssignmentInput {
   arrivalDate?: string | null;
   notes?: string | null;
 }
-interface UpdateSapAssignmentInput {
+/** A scope, when sent, must match the assignment's own event or year. */
+interface UpdateSapAssignmentInput extends EventScopeParams {
   assignmentId: string;
   sapNumber?: string | null;
   vehicleDescription?: string | null;
@@ -1291,8 +1455,10 @@ interface BikeRentalInterestedMember {
   unmatchable: boolean;
 }
 interface BikeRentalInterestedNotReservedResponse {
-  /** Active camp year; the calendar year when no camp year is active. */
+  /** Camp year of the list; for an event, its start year. */
   year: number;
+  /** Event the list is for; null on the annual path. */
+  eventId: string | null;
   items: BikeRentalInterestedMember[];
 }
 /** Email template registry entry (PLA-1265). */
@@ -1352,6 +1518,8 @@ interface Meeting {
   id: string;
   orgId: string;
   year: number;
+  /** Canonical event the meeting belongs to (ADR-132); null for an annual camp meeting. */
+  eventId?: string | null;
   title: string;
   description: string | null;
   isMandatory: boolean;
@@ -1360,7 +1528,8 @@ interface Meeting {
   createdAt: string;
   dateOptions: MeetingDateOption[];
 }
-interface CreateMeetingInput {
+/** With neither `year` nor `eventId`, the meeting joins the active camp year (ADR-132). */
+interface CreateMeetingInput extends EventScopeParams {
   notifyMembers?: boolean;
   title: string;
   description?: string | null;
@@ -1381,7 +1550,8 @@ interface Scholarship {
   id: string;
   orgId: string;
   userId: string;
-  year: number;
+  eventId: string | null;
+  year: number | null;
   promoCode: string;
   discountAmount: string;
   reason: string | null;
@@ -1390,15 +1560,29 @@ interface Scholarship {
   discountCodeId: string | null;
 }
 interface CreateScholarshipInput {
+  /**
+   * Givebutter-managed code. Scoped like any create: on an event it maps to the event's Base Dues
+   * tier and needs a published event the member takes part in (else 409 CONFLICT).
+   */
   providerManaged?: boolean;
   userId: string;
   promoCode: string;
   discountAmount: number;
   reason?: string;
+  /**
+   * Legacy camp year (ADR-132). A year with one event creates an event scholarship; a year with
+   * several is 409 `EVENT_REQUIRED`. With neither field, the camp's configured active year.
+   */
   year?: number;
+  /** Canonical event ID. When sent with `year`, both must agree (else 400). */
+  eventId?: string;
 }
 type TicketStatus = "have_ticket" | "need_ticket" | "step_enrolled" | "low_income_approved";
 interface AdminTicketRow extends Ticket {
+  /** Event rows: the participation status (e.g. `confirmed`, `pending`). Null for annual rows. */
+  participationStatus: string | null;
+  /** Event rows: the participation's attendance response. Null for annual rows. */
+  attendanceResponse: string | null;
   vehiclePassStatus: VehiclePassStatus | null;
   vehiclePassConfirmation: string | null;
   member: {
@@ -1408,10 +1592,13 @@ interface AdminTicketRow extends Ticket {
   } | null;
 }
 interface Ticket {
+  /** Annual rows: the member_camp_years id (usable with `update`). Event rows: the event participation id. */
   id: string;
   orgId: string;
   userId: string;
   year: number;
+  /** The event this row belongs to; null for an annual row (ADR-132). */
+  eventId: string | null;
   ticketStatus: string | null;
   ticketConfirmationNumber: string | null;
   ticketNotes: string | null;
@@ -1423,10 +1610,13 @@ interface TicketUpdateInput {
 }
 type VehiclePassStatus = "need_pass" | "have_pass" | "not_needed";
 interface VehiclePass {
+  /** Annual rows: the member_camp_years id (usable with `update`). Event rows: the event participation id. */
   id: string;
   orgId: string;
   userId: string;
   year: number;
+  /** The event this row belongs to; null for an annual row (ADR-132). */
+  eventId: string | null;
   vehiclePassStatus: VehiclePassStatus | null;
   vehiclePassConfirmation: string | null;
 }
@@ -1496,6 +1686,28 @@ interface MemberBootstrap {
     externalUrl: string | null;
   }>;
 }
+/** Acting member's dues flags and payment history for one event or camp year (ADR-132). */
+interface MemberPaymentsOverview {
+  year: number;
+  /** The event read, or null on the annual path. */
+  eventId: string | null;
+  duesStatus: {
+    hasPaidBaseDues: boolean;
+    hasPaidRvDues: boolean;
+    ownsRvShelter: boolean;
+    rvAmperage: number | null;
+    rvType: string | null;
+    totalPaid: number;
+  };
+  payments: Array<{
+    id: string;
+    amount: number;
+    paymentMethod: string | null;
+    paymentStatus: string | null;
+    paymentDate: string | null;
+  }>;
+  donationWidgetId: string | null;
+}
 interface MemberDashboard {
   year: number;
   profile: MemberSelfProfile;
@@ -1622,7 +1834,7 @@ type ShiftAdminOperation = {
 } | {
   action: "delete_type";
   id: string;
-} | {
+} | ({
   action: "create_shift";
   shiftTypeId: string;
   shiftDate: string;
@@ -1630,7 +1842,7 @@ type ShiftAdminOperation = {
   endTime: string;
   maxSlots: number;
   notes?: string;
-} | {
+} & EventScopeParams) | {
   action: "update_shift";
   id: string;
   maxSlots?: number;
@@ -1640,21 +1852,21 @@ type ShiftAdminOperation = {
 } | {
   action: "delete_shift";
   id: string;
-} | {
+} | ({
   action: "bulk_create";
   shiftTypeId: string;
   dates: string[];
   startTime: string;
   endTime: string;
   maxSlots: number;
-} | {
+} & EventScopeParams) | ({
   action: "clear_day";
   date: string;
-} | {
+} & EventScopeParams) | ({
   action: "copy_day";
   sourceDate: string;
   targetDate: string;
-} | {
+} & EventScopeParams) | {
   action: "remove_signup";
   id: string;
 } | {
@@ -1757,9 +1969,9 @@ type ShiftAdminWorkflow = {
   shiftId: string;
   shelterId: string;
   forceAssign?: boolean;
-} | {
+} | ({
   action: "publish";
-};
+} & EventScopeParams);
 interface ShiftAdminWorkflowResult {
   assignedCount?: number;
   skippedCount?: number;
@@ -1769,6 +1981,8 @@ interface ShiftAdminWorkflowResult {
 }
 interface ShiftPlannerData {
   year: number;
+  /** Resolved event, or null on the annual path (ADR-132). */
+  eventId: string | null;
   members: Array<{
     id: string;
     name: string;
@@ -1928,6 +2142,10 @@ interface MemberDocumentPage {
   }>;
 }
 interface MemberShiftView {
+  /** Resolved scope year (ADR-132). */
+  year: number;
+  /** Resolved event, or null on the annual path (ADR-132). */
+  eventId: string | null;
   arrivalDate: string | null;
   departureDate: string | null;
   shifts: Array<{
@@ -1941,7 +2159,11 @@ interface MemberShiftView {
     coworkers: string[];
   }>;
 }
-type AdminShelterOperation = {
+/**
+ * Every operation takes an ADR-132 scope. With an event, the shelter or assignment must belong to it
+ * and placed members must be confirmed, attending participants; without one, annual rows only.
+ */
+type AdminShelterOperation = EventScopeParams & ({
   action: "approve" | "remove";
   assignmentId: string;
 } | {
@@ -1973,8 +2195,12 @@ type AdminShelterOperation = {
 } | {
   action: "delete";
   shelterId: string;
-};
+});
 interface MobileShifts {
+  /** Resolved scope year (ADR-132). */
+  year: number;
+  /** Resolved event, or null on the annual path (ADR-132). */
+  eventId: string | null;
   shifts: Array<{
     id: string;
     date: string;
@@ -2001,6 +2227,8 @@ interface MobileShifts {
 }
 interface AdminCampSettings {
   year: number;
+  /** The event read, or null on the annual path (ADR-132). */
+  eventId: string | null;
   slotLimits: Record<string, number>;
   feeTiers: Array<{
     id: string;
@@ -2023,12 +2251,12 @@ interface AdminCampSettings {
 type CampSettingsOperation = {
   action: "slot_limits";
   limits: Record<string, number>;
-} | {
+} | ({
   action: "fee_tier";
   id: string;
   displayName: string;
   amount: number;
-} | {
+} & EventScopeParams) | {
   action: "reminder";
   type: "payment" | "onboarding" | "documents" | "logistics_undecided" | "photo_avatar" | "photo_fullsize" | "attendance_nudge";
   enabled: boolean;
@@ -2073,30 +2301,31 @@ interface AdminBikeOperationResult {
   sent?: number;
   failed?: number;
 }
-type AdminPaymentOperation = {
+type AdminPaymentOperation = ({
   action: "manual_payment";
   payerId: string;
   paidForUserId?: string | null;
   amount: number;
   method: string;
   notes?: string;
-  year?: number;
-} | {
+} & EventScopeParams) |
+/** The fee tier decides the scope; a sent `eventId`/`year` must agree with it. */
+({
   action: "assign_fee";
   memberId: string;
   feeTierId: string;
   feeType: "base" | "addon";
-} | {
+} & EventScopeParams) | {
   action: "refund";
   paymentId: string;
 } | {
   action: "link_refund";
   refundEventId: string;
   paymentId: string;
-} | {
+} | ({
   action: "nudge";
   memberIds: string[];
-};
+} & EventScopeParams);
 interface AdminPaymentOperationResult {
   success: true;
   paymentId?: string;
@@ -2143,6 +2372,11 @@ interface SchedulingAdminResult {
   success?: boolean;
 }
 interface SchedulingAdminSettings {
+  /** Missing on older servers; an empty array means no active camp booking links. */
+  bookingLinks?: {
+    id: string;
+    title: string;
+  }[];
   googleConnected: boolean;
   interviewer: {
     id: string;
@@ -2208,6 +2442,8 @@ interface AdminImportantDate {
   notifyDaysBefore: number[] | null;
   isSystem: boolean | null;
   slug: string | null;
+  /** Canonical event the date belongs to (ADR-132); null for an annual camp date. */
+  eventId?: string | null;
 }
 interface AdminImportantDateInput {
   title: string;
@@ -2217,9 +2453,12 @@ interface AdminImportantDateInput {
   category: "dues" | "documents" | "tickets" | "event" | "other" | "system";
   notifyDaysBefore: number[];
 }
-type AdminImportantDateOperation = {
+type AdminImportantDateOperation =
+/** `eventId` attaches the date to an event the camp owns (ADR-132); without it, an annual date. */
+{
   action: "create";
   input: AdminImportantDateInput;
+  eventId?: string;
 } | {
   action: "update";
   id: string;
@@ -2230,6 +2469,8 @@ type AdminImportantDateOperation = {
 };
 interface AdminPaymentsPage {
   year: number;
+  /** The event read, or null on the annual path (ADR-132). */
+  eventId: string | null;
   transactions: {
     id: string;
     userId: string | null;
@@ -2280,14 +2521,17 @@ interface ScholarshipStats {
 }
 interface AdminScholarshipsPage {
   year: number;
+  /** The event read, or null on the annual path (ADR-132). */
+  eventId: string | null;
   scholarships: {
     id: string;
     userId: string;
+    eventId: string | null;
     promoCode: string;
     discountAmount: string;
     reason: string | null;
     status: ScholarshipStatus;
-    year: number;
+    year: number | null;
     usedAt: string | null;
     createdAt: string | null;
     profile: {
@@ -2344,14 +2588,21 @@ type AdminMemberOperation = {
   action: "attendance";
   profileId: string;
   attendanceResponse: "attending" | "not_attending" | "undecided" | null;
-  /** Defaults to the active camp year. An explicit year must already have a camp year row. */
+  /** Defaults to the active camp year. An explicit year with no event must already have a camp year row. */
   year?: number;
+  /**
+   * Edits this event's participation (ADR-132). 404 `PARTICIPATION_NOT_FOUND` when the member has
+   * none; an admin edit never creates one.
+   */
+  eventId?: string;
 } | {
   action: "profile";
   profileId: string;
   profile?: MemberProfileUpdate;
   campYear?: Omit<MemberTravelUpdate, "attendanceResponse">;
   year?: number;
+  /** Edits this event's participation; see `attendance`. */
+  eventId?: string;
 } | {
   action: "delete";
   profileId: string;
@@ -2362,8 +2613,13 @@ type AdminMemberOperation = {
   profileId: string;
   wantsBikeRental: boolean;
   bikeTypePreference: "ebike" | "pedal" | null;
-  /** Defaults to the active camp year. An explicit year must already have a camp year row. */
+  /** Defaults to the active camp year. An explicit year with no event must already have a camp year row. */
   year?: number;
+  /**
+   * Edits this event's participation (ADR-132). 404 `PARTICIPATION_NOT_FOUND` when the member has
+   * none; an admin edit never creates one.
+   */
+  eventId?: string;
 } | {
   action: "summer_rsvp";
   profileId: string;
@@ -2435,6 +2691,8 @@ type BookkeepingAdminOperation = {
 };
 interface AdminGivebutterWidgets {
   year: number;
+  /** The event read, or null on the annual path (ADR-132). */
+  eventId: string | null;
   widgets: {
     id: string;
     category: string;
@@ -2442,16 +2700,17 @@ interface AdminGivebutterWidgets {
     widgetId: string;
     label: string | null;
     isActive: boolean;
-    year: number;
+    /** Null for an event widget. */
+    year: number | null;
   }[];
 }
-type AdminGivebutterWidgetOperation = {
+type AdminGivebutterWidgetOperation = ({
   action: "upsert";
   category: "dues" | "rv_addon" | "donation";
   tierKey: string;
   widgetId: string;
   label: string | null;
-} | {
+} & EventScopeParams) | {
   action: "delete";
   id: string;
 } | {
@@ -2593,12 +2852,12 @@ interface AdminGivebutterCatalog {
 }
 type AdminGivebutterCatalogOperation = {
   action: "sync";
-} | {
+} | ({
   action: "set_active_tier";
   tier: "base_dues";
   campaignId: number;
   itemId: number;
-};
+} & EventScopeParams);
 type PackingContainerType = "hdx_tote" | "suitcase" | "box" | "bag" | "other";
 interface PackingContainer {
   id: string;
@@ -2770,6 +3029,14 @@ interface ClientOptions {
    */
   memberToken?: string;
 }
+/**
+ * Methods that took only `opts` before gaining scope params still read a `signal` from their first
+ * argument, so `method({ signal })` keeps working.
+ */
+interface LegacySignalOption {
+  /** @deprecated Pass `signal` in the second argument. */
+  signal?: AbortSignal;
+}
 export declare class PlayaOSClient {
   private readonly baseUrl;
   private readonly embedBaseUrl;
@@ -2839,8 +3106,13 @@ export declare class PlayaOSClient {
       cancelled: true;
     }>;
   };
+  /**
+   * 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.
+   */
   readonly campSettings: {
-    catalog: (opts?: {
+    catalog: (params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<AdminGivebutterCatalog>;
     catalogOperation: (payload: AdminGivebutterCatalogOperation, opts?: {
@@ -2850,7 +3122,7 @@ export declare class PlayaOSClient {
       campaigns?: number;
       items?: number;
     }>;
-    widgets: (opts?: {
+    widgets: (params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<AdminGivebutterWidgets>;
     widgetOperation: (payload: AdminGivebutterWidgetOperation, opts?: {
@@ -2858,7 +3130,7 @@ export declare class PlayaOSClient {
     }) => Promise<{
       success: true;
     }>;
-    admin: (opts?: {
+    admin: (params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<AdminCampSettings>;
     update: (payload: CampSettingsOperation, opts?: {
@@ -2877,14 +3149,17 @@ export declare class PlayaOSClient {
     adminOperation: (payload: SchedulingAdminOperation, opts?: {
       signal?: AbortSignal;
     }) => Promise<SchedulingAdminResult>;
-    feed: (interviewerId: string, token: string, opts?: {
+    /**
+     * 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: string, token: string, params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<InterviewFeedBooking[]>;
   };
   readonly members: {
-    adminExport: (params: {
-      year: number;
-    }, opts?: {
+    /** Exports one event, or a year with one event (ADR-132); with neither, the active camp year. */
+    adminExport: (params?: EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       data: AdminMemberExportRow[];
@@ -2899,9 +3174,8 @@ export declare class PlayaOSClient {
     adminImportOperation: (payload: AdminImportOperation, opts?: {
       signal?: AbortSignal;
     }) => Promise<AdminImportResult>;
-    adminDetail: (id: string, params?: {
-      year?: number;
-    }, opts?: {
+    /** On an event, `campYear` holds that event's participation (ADR-132). */
+    adminDetail: (id: string, params?: EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<MemberProfileDetails>;
     adminHistory: (id: string, opts?: {
@@ -2995,6 +3269,20 @@ export declare class PlayaOSClient {
     dashboard: (opts?: {
       signal?: AbortSignal;
     }) => Promise<MemberDashboard>;
+    /**
+     * 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?: EventScopeParams & LegacySignalOption, opts?: {
+      signal?: AbortSignal;
+    }) => Promise<MemberPaymentsOverview>;
+    /** Acting member's original photo only; missing originals return 404, never an avatar fallback. */
+    selfPhotoDownloadUrl: (opts?: {
+      signal?: AbortSignal;
+    }) => Promise<{
+      url: string;
+      fileName: string;
+    }>;
     /** Presigned profile-photo upload (PLA-1263). PUT the bytes, then setPhoto. */
     createPhotoUploadUrl: (payload: {
       contentType: "image/jpeg" | "image/png" | "image/webp";
@@ -3060,6 +3348,8 @@ export declare class PlayaOSClient {
       sortBy?: "name" | "email" | "role" | "status" | "createdAt";
       sortOrder?: "asc" | "desc";
       attending?: "true" | "false";
+      /** Canonical event to scope `attending` to; alone, lists that event's participants. */
+      eventId?: string;
     } & PaginationParams & {
       /** Raw row offset — the members table's pager. Mutually exclusive with `cursor`. */
       offset?: number;
@@ -3161,10 +3451,11 @@ export declare class PlayaOSClient {
     }) => Promise<SummerCampRsvp>;
   };
   readonly applications: {
-    list: (params?: {
+    list: (
+    /** `eventId` or `year` narrows to one event, or a year with no event (ADR-132); neither lists every year. */
+    params?: {
       status?: ApplicationStatus;
-      year?: number;
-    } & PaginationParams, opts?: {
+    } & EventScopeParams & PaginationParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<Paginated<Application>>;
     create: (payload: ApplicationCreatePayload, opts?: {
@@ -3200,9 +3491,8 @@ export declare class PlayaOSClient {
   readonly dues: {
     list: (params?: {
       userId?: string;
-      year?: number;
       paymentStatus?: "unpaid" | "partial" | "paid";
-    } & PaginationParams, opts?: {
+    } & EventScopeParams & PaginationParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<Paginated<DuesStatus>>;
   };
@@ -3218,21 +3508,22 @@ export declare class PlayaOSClient {
     }) => Promise<{
       success: true;
     }>;
+    /** Without a scope, the configured active camp year (ADR-132). */
     mobile: (params: {
       type: "available" | "my-shifts";
       date: string;
-    }, opts?: {
+    } & EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<MobileShifts>;
-    memberView: (opts?: {
+    /** Without a scope, the configured active camp year (ADR-132). */
+    memberView: (params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<MemberShiftView>;
     adminWorkflow: (payload: ShiftAdminWorkflow, opts?: {
       signal?: AbortSignal;
     }) => Promise<ShiftAdminWorkflowResult>;
-    planner: (params?: {
-      year?: number;
-    }, opts?: {
+    /** Without a scope, the configured active camp year (ADR-132). */
+    planner: (params?: EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<ShiftPlannerData>;
     adminOperation: (payload: ShiftAdminOperation, opts?: {
@@ -3241,18 +3532,17 @@ export declare class PlayaOSClient {
     adminTypes: (opts?: {
       signal?: AbortSignal;
     }) => Promise<AdminShiftType[]>;
-    adminList: (params?: {
-      year?: number;
-    } & PaginationParams, opts?: {
+    /** With neither `year` nor `eventId`, every shift in the org (documented ADR-132 exception). */
+    adminList: (params?: EventScopeParams & PaginationParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<Paginated<AdminShift>>;
+    /** With neither `year` nor `eventId`, every shift in the org (documented ADR-132 exception). */
     list: (params?: {
-      year?: number;
       fromDate?: string;
       toDate?: string;
       publishedOnly?: boolean;
       openOnly?: boolean;
-    } & PaginationParams, opts?: {
+    } & EventScopeParams & PaginationParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<Paginated<Shift>>;
   };
@@ -3267,9 +3557,7 @@ export declare class PlayaOSClient {
     }) => Promise<CommitmentsListResponse>;
   };
   readonly payments: {
-    adminPage: (params?: {
-      year?: number;
-    }, opts?: {
+    adminPage: (params?: EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<AdminPaymentsPage>;
     adminOperation: (payload: AdminPaymentOperation, opts?: {
@@ -3287,13 +3575,13 @@ export declare class PlayaOSClient {
       paymentDate: string | null;
       paymentMethod: string | null;
     }>>;
-    adminSummary: (opts?: {
+    adminSummary: (params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<AdminPaymentSummary>;
     exportMonarch: (params?: {
       from?: string;
       to?: string;
-    }, opts?: {
+    } & EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       csv: string;
@@ -3335,40 +3623,40 @@ export declare class PlayaOSClient {
   };
   /** Logistics dashboard reads (PLA-1342): rollup, daily headcount, unsure dates, area breakdowns. */
   readonly logistics: {
-    summary: (params: {
-      year: number;
-    }, opts?: {
+    /** Requires `eventId` or `year` (ADR-132); an ambiguous year rejects with EVENT_REQUIRED. */
+    summary: (params: EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<LogisticsSummary>;
-    headcount: (params?: PaginationParams, opts?: {
+    /** Without a scope, the org's active camp year. */
+    headcount: (params?: EventScopeParams & PaginationParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<Paginated<DailyHeadcount>>;
-    unsureDates: (params?: {
-      year?: number;
-    } & PaginationParams, opts?: {
+    /** Without a scope, every camp year. */
+    unsureDates: (params?: EventScopeParams & PaginationParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<Paginated<UnsureDateMember>>;
-    breakdowns: (opts?: {
+    /** Without a scope, the org's active camp year. */
+    breakdowns: (params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<LogisticsBreakdowns>;
   };
   /** Admin reports (PLA-1343): dashboard rollup + build/strike availability. */
   readonly reports: {
+    /** Requires `eventId` or `year` (ADR-132); an ambiguous year rejects with EVENT_REQUIRED. */
     dashboard: (params: {
-      year: number;
       asOf: string;
-    }, opts?: {
+    } & EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<DashboardMetrics>;
-    buildStrike: (params: {
-      year: number;
-    }, opts?: {
+    /** Requires `eventId` or `year` (ADR-132); an ambiguous year rejects with EVENT_REQUIRED. */
+    buildStrike: (params: EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<BuildStrikeReportRow[]>;
   };
   /** Bookkeeping reads (PLA-1345): camp-year list + ops-binder export preview. */
   readonly bookkeeping: {
-    syncGoogleSheets: (opts?: {
+    /** Without a scope, the camp's active year (ADR-132). */
+    syncGoogleSheets: (params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<SheetsSyncResult>;
     adminOperation: (payload: BookkeepingAdminOperation, opts?: {
@@ -3379,9 +3667,12 @@ export declare class PlayaOSClient {
     years: (opts?: {
       signal?: AbortSignal;
     }) => Promise<CampYearWithCounts[]>;
-    exportPreview: (params?: {
-      year?: number;
-    }, opts?: {
+    /** Requires `eventId` or `year` (ADR-132); an ambiguous year rejects with EVENT_REQUIRED. */
+    summary: (params: EventScopeParams, opts?: {
+      signal?: AbortSignal;
+    }) => Promise<BookkeepingSummary>;
+    /** Without a scope, the org's operational year. */
+    exportPreview: (params?: EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<BookkeepingExportPreview>;
   };
@@ -3436,12 +3727,12 @@ export declare class PlayaOSClient {
     }) => Promise<NotificationLog[]>;
   };
   readonly documents: {
-    memberPage: (params?: {
-      year?: number;
-    }, opts?: {
+    /** Scope with `eventId` or `year` (ADR-132); with neither, the active camp year. */
+    memberPage: (params?: EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<MemberDocumentPage>;
-    create: (payload: DocumentWriteInput, opts?: {
+    /** `eventId` attaches the document to that event (ADR-132); with neither scope, the active camp year. */
+    create: (payload: DocumentWriteInput & EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<CampDocument>;
     update: (id: string, payload: Partial<DocumentWriteInput>, opts?: {
@@ -3499,11 +3790,11 @@ export declare class PlayaOSClient {
       id: string;
       deleted: true;
     }>;
+    /** With `eventId`, only that event's documents (ADR-132); with no scope, every document. */
     list: (params?: {
       type?: string;
-      year?: number;
       activeYear?: boolean;
-    }, opts?: {
+    } & EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<AdminCampDocument[]>;
     get: (id: string, opts?: {
@@ -3549,11 +3840,11 @@ export declare class PlayaOSClient {
     }) => Promise<{
       ok: true;
     }>;
+    /** With `eventId`, only that event's meetings (ADR-132); with no scope, every meeting. */
     list: (params?: {
-      year?: number;
       limit?: number;
       cursor?: string;
-    }, opts?: {
+    } & EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<MeetingListResponse>;
     get: (id: string, opts?: {
@@ -3572,9 +3863,12 @@ export declare class PlayaOSClient {
     }>;
   };
   readonly scholarships: {
-    adminPage: (params?: {
-      year?: number;
-    }, opts?: {
+    /**
+     * 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?: EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<AdminScholarshipsPage>;
     refresh: (id: string, opts?: {
@@ -3583,12 +3877,15 @@ export declare class PlayaOSClient {
       givebutterActive: boolean;
       givebutterUsed: number;
     }>;
-    stats: (params?: {
-      year?: number;
-    }, opts?: {
+    /** Scholarship totals for an event or year; same scope rules and 409 `EVENT_REQUIRED` as `adminPage`. */
+    stats: (params?: EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<ScholarshipStats>;
-    /** 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: CreateScholarshipInput, opts?: {
       signal?: AbortSignal;
     }) => Promise<Scholarship>;
@@ -3612,10 +3909,21 @@ export declare class PlayaOSClient {
     upsert: (memberId: string, year: number, payload: TicketUpdateInput, opts?: {
       signal?: AbortSignal;
     }) => Promise<Ticket>;
-    /** Admin ticket-page projection; requires ticket, vehicle-pass, and member read scopes. */
-    adminList: (params?: {
+    /**
+     * 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: string, eventId: string, payload: TicketUpdateInput, opts?: {
       year?: number;
-    } & PaginationParams, opts?: {
+      signal?: AbortSignal;
+    }) => Promise<Ticket>;
+    /**
+     * 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?: EventScopeParams & PaginationParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<Paginated<AdminTicketRow>>;
     /** Update a member's ticket status/confirmation. Admin-only (PLA-1266). */
@@ -3628,6 +3936,15 @@ export declare class PlayaOSClient {
     upsert: (memberId: string, year: number, payload: VehiclePassUpdateInput, opts?: {
       signal?: AbortSignal;
     }) => Promise<VehiclePass>;
+    /**
+     * 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: string, eventId: string, payload: VehiclePassUpdateInput, opts?: {
+      year?: number;
+      signal?: AbortSignal;
+    }) => Promise<VehiclePass>;
     /** Update a member's vehicle-pass status. Admin-only (PLA-1266). */
     update: (id: string, payload: VehiclePassUpdateInput, opts?: {
       signal?: AbortSignal;
@@ -3641,25 +3958,25 @@ export declare class PlayaOSClient {
       shelterId?: string;
       feesRecalculated?: boolean;
     }>;
-    createForMember: (payload: OwnerShelterCreate, opts?: {
+    /** With an event scope, the acting member and any mates must be confirmed, attending participants. */
+    createForMember: (payload: OwnerShelterCreate & EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       shelterId: string;
       shareUrl: string | null;
     }>;
-    updateForMember: (id: string, payload: OwnerShelterPatch, opts?: {
+    /** A scope, when sent, must match the shelter's own event; without one, annual shelters only. */
+    updateForMember: (id: string, payload: OwnerShelterPatch, params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       updated: true;
     }>;
-    deleteForMember: (id: string, opts?: {
+    deleteForMember: (id: string, params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       shelterType: string;
     }>;
-    memberPage: (params?: {
-      year?: number;
-    }, opts?: {
+    memberPage: (params?: EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<MemberShelterPage>;
     searchMembers: (params: {
@@ -3672,12 +3989,12 @@ export declare class PlayaOSClient {
         name: string | null;
       }>;
     }>;
-    requestJoin: (id: string, opts?: {
+    requestJoin: (id: string, params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       id: string;
     }>;
-    inviteCandidates: (id: string, opts?: {
+    inviteCandidates: (id: string, params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       data: Array<{
@@ -3707,15 +4024,12 @@ export declare class PlayaOSClient {
     }>;
     requestPayer: (payload: {
       payerUserId: string;
-      year?: number;
-    }, opts?: {
+    } & EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       existingShelterId: string | null;
     }>;
-    pendingPayerRequests: (params?: {
-      year?: number;
-    }, opts?: {
+    pendingPayerRequests: (params?: EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       data: Array<{
@@ -3730,48 +4044,49 @@ export declare class PlayaOSClient {
         assignmentId: string;
         approved: boolean;
       }>;
-    }, opts?: {
+    } & EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       success: true;
     }>;
-    /** Admin-only shelter table/map projection; requires members:read and a member token. */
-    adminList: (params: {
-      year: number;
-    } & PaginationParams, opts?: {
+    /**
+     * 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: EventScopeParams & PaginationParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<Paginated<AdminShelter>>;
     list: (params?: {
       ownerId?: string;
       shelterType?: string;
-      year?: number;
-    }, opts?: {
+    } & EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<Shelter[]>;
-    get: (id: string, opts?: {
+    /** Without a scope only annual shelters match; send `eventId` to read an event's shelter. */
+    get: (id: string, params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<Shelter>;
-    /** Request to join a shelter (member). PLA-1260. */
-    join: (shelterId: string, opts?: {
+    /** Request to join a shelter (member). PLA-1260. A scope must match the shelter's event. */
+    join: (shelterId: string, params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       id: string;
     }>;
-    /** Invite a member to a shelter the acting member owns. PLA-1260. */
-    invite: (shelterId: string, inviteeUserId: string, opts?: {
+    /** Invite a member to a shelter the acting member owns. PLA-1260. A scope must match the shelter's event. */
+    invite: (shelterId: string, inviteeUserId: string, params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       id: string;
     }>;
     /** Leave a shelter (deletes the acting member's own assignment). PLA-1260. */
-    leave: (assignmentId: string, opts?: {
+    leave: (assignmentId: string, params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       id: string;
       deleted: boolean;
     }>;
     /** Accept or decline a shelter invitation. PLA-1260. */
-    respond: (assignmentId: string, accept: boolean, opts?: {
+    respond: (assignmentId: string, accept: boolean, params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       id: string;
@@ -3869,8 +4184,11 @@ export declare class PlayaOSClient {
     requestReservation: (payload: BikeRentalRequestInput, opts?: {
       signal?: AbortSignal;
     }) => Promise<BikeRentalRequestResult>;
-    /** Members who said they want a bike but have no reservation, for the active camp year. Org key only. */
-    interestedNotReserved: (opts?: {
+    /**
+     * Members who said they want a bike but have no reservation, for one event or camp year. With
+     * no params, the camp's configured active camp year. Org key only.
+     */
+    interestedNotReserved: (params?: EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<BikeRentalInterestedNotReservedResponse>;
   };
@@ -4090,10 +4408,10 @@ export declare 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. */
   readonly sap: {
-    roster: (params?: {
-      year?: number;
-    }, opts?: {
+    /** With an event scope, the event's participants instead of the year's roster. */
+    roster: (params?: EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<Array<{
       id: string;
@@ -4104,8 +4422,7 @@ export declare class PlayaOSClient {
       buildArrivalDate: string | null;
     }>>;
     allocation: {
-      get: (opts?: {
-        year?: number;
+      get: (params?: EventScopeParams & LegacySignalOption, opts?: {
         signal?: AbortSignal;
       }) => Promise<SapAllocation>;
       update: (payload: UpdateSapAllocationInput, opts?: {
@@ -4116,30 +4433,29 @@ export declare class PlayaOSClient {
       update: (id: string, payload: {
         slotsAvailable: number;
         notes?: string | null;
-      }, opts?: {
+      } & EventScopeParams, opts?: {
         signal?: AbortSignal;
       }) => Promise<{
         ok: true;
       }>;
-      remove: (id: string, opts?: {
+      /** A scope, when sent, must match the row's own event or year. */
+      remove: (id: string, params?: EventScopeParams & LegacySignalOption, opts?: {
         signal?: AbortSignal;
       }) => Promise<{
         ok: true;
       }>;
-      list: (opts?: {
-        year?: number;
+      list: (params?: EventScopeParams & LegacySignalOption, opts?: {
         signal?: AbortSignal;
       }) => Promise<{
         items: SapDayAllocation[];
       }>;
-      /** Upserts by (active year, accessDate); 409 on a cross-org date collision. */
+      /** Upserts by (scope, accessDate); 409 on a date collision or an ambiguous year. */
       upsert: (payload: UpsertSapDayAllocationInput, opts?: {
         signal?: AbortSignal;
       }) => Promise<SapDayAllocation>;
     };
     assignments: {
-      list: (opts?: {
-        year?: number;
+      list: (params?: EventScopeParams & LegacySignalOption, opts?: {
         signal?: AbortSignal;
       }) => Promise<{
         items: SapAssignment[];
@@ -4150,7 +4466,7 @@ export declare class PlayaOSClient {
       update: (payload: UpdateSapAssignmentInput, opts?: {
         signal?: AbortSignal;
       }) => Promise<SapAssignment>;
-      remove: (assignmentId: string, opts?: {
+      remove: (assignmentId: string, params?: EventScopeParams & LegacySignalOption, opts?: {
         signal?: AbortSignal;
       }) => Promise<{
         ok: true;
@@ -4158,7 +4474,8 @@ export declare class PlayaOSClient {
     };
   };
   readonly importantDates: {
-    adminList: (opts?: {
+    /** Scope with `eventId` or `year` (ADR-132); with neither, the active camp year (409 when none). */
+    adminList: (params?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<AdminImportantDate[]>;
     adminOperation: (payload: AdminImportantDateOperation, opts?: {
@@ -4166,28 +4483,38 @@ export declare class PlayaOSClient {
     }) => Promise<{
       success: true;
     }>;
-    /** 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?: EventScopeParams, opts?: {
+      signal?: AbortSignal;
+    }) => Promise<ImportantDate[]>;
+  };
+  readonly events: {
+    /** The camp's events with the given status (default `published`), earliest first. */
     list: (params?: {
-      year?: number;
+      status?: EventStatus;
     }, opts?: {
       signal?: AbortSignal;
-    }) => Promise<ImportantDate[]>;
+    }) => Promise<EventSummary[]>;
   };
   readonly emails: {
-    recipients: (payload: EmailRecipientFilter, opts?: {
+    /** Payment, attendance and build-week filters follow `eventId` or `year` (ADR-132). */
+    recipients: (payload: EmailRecipientFilter & EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<EmailRecipient[]>;
+    /** Year-dependent segment counts follow `eventId` or `year`; null when unscoped with no camp year. */
     composerOptions: (params?: {
       q?: string;
-    }, opts?: {
+    } & EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<EmailComposerOptions>;
-    broadcast: (payload: {
+    broadcast: (
+    /** A provider segment is camp-wide and takes no `eventId` (ADR-132). */
+    payload: {
       subject: string;
       body: string;
       filter?: EmailRecipientFilter;
       segmentKey?: EmailSegmentKey;
-    }, opts?: {
+    } & EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       success: true;
@@ -4197,7 +4524,11 @@ export declare class PlayaOSClient {
       failed: number;
       total: number;
     }>;
-    history: (opts?: {
+    /**
+     * 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?: EventScopeParams & LegacySignalOption, opts?: {
       signal?: AbortSignal;
     }) => Promise<{
       broadcasts: {
@@ -4320,22 +4651,19 @@ export declare class PlayaOSClient {
     /** Per-member checklist completion; non-admins are pinned to themselves. */
     progress: (params?: {
       userId?: string;
-      year?: number;
-    } & PaginationParams, opts?: {
+    } & EventScopeParams & PaginationParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<Paginated<OnboardingProgress>>;
     /** The acting member's own custom checklist items for a year (PLA-1340). */
     customItems: (params?: {
       userId?: string;
-      year?: number;
-    } & PaginationParams, opts?: {
+    } & EventScopeParams & PaginationParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<Paginated<MemberCustomChecklistItem>>;
     /** Tick a checklist item for the acting member (PLA-1259). */
     setProgress: (itemId: string, payload: {
       completed: boolean;
-      year?: number;
-    }, opts?: {
+    } & EventScopeParams, opts?: {
       signal?: AbortSignal;
     }) => Promise<OnboardingProgress>;
   };
@@ -4411,21 +4739,19 @@ export declare class PlayaOSClient {
        */
       list: (params?: {
         status?: ApplicationStatus;
-        year?: number;
         virginBurner?: "true" | "false";
         hasReferral?: "true" | "false";
         q?: string;
-      } & PaginationParams, opts?: {
+      } & EventScopeParams & PaginationParams, opts?: {
         signal?: AbortSignal;
       }) => Promise<Paginated<ApplicationAdmin>>;
       /**
-       * 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?: {
-        year?: number;
-      }, opts?: {
+      capacity: (params?: EventScopeParams, opts?: {
         signal?: AbortSignal;
       }) => Promise<ApplicationCapacity>;
       /**
@@ -4544,23 +4870,21 @@ export declare class PlayaOSClient {
         accessToken?: string;
         signal?: AbortSignal;
       }) => Promise<DuesUpdateResponse>;
-      /** Per-member dues state from `member_dues_status` (PLA-1336). V1-only — requires a member token. */
-      status: (params?: {
-        year?: number;
-      }, opts?: {
+      /**
+       * Per-member dues state for one event or camp year (PLA-1336, ADR-132). With no params, the
+       * configured active camp year. V1-only — requires a member token.
+       */
+      status: (params?: EventScopeParams, opts?: {
         signal?: AbortSignal;
       }) => Promise<MemberDuesStatus[]>;
-      /** Per-tier dues totals from `dues_summary` (PLA-1336). V1-only — requires a member token. */
-      summary: (params?: {
-        year?: number;
-      }, opts?: {
+      /** Per-tier dues totals for one event or camp year (PLA-1336, ADR-132). V1-only — requires a member token. */
+      summary: (params?: EventScopeParams, opts?: {
         signal?: AbortSignal;
       }) => Promise<DuesSummaryRow[]>;
-      /** Members who paid a given dues type (PLA-1336). V1-only — requires a member token. */
+      /** Members who paid a given dues type, for one event or camp year (PLA-1336, ADR-132). V1-only — requires a member token. */
       payors: (params: {
         duesType: string;
-        year: number;
-      }, opts?: {
+      } & EventScopeParams, opts?: {
         signal?: AbortSignal;
       }) => Promise<DuesTypePayor[]>;
     };
@@ -4759,5 +5083,5 @@ interface PublicMarketplaceClient {
 }
 export declare function createPublicMarketplaceClient(opts: PublicMarketplaceClientOptions): PublicMarketplaceClient;
 //#endregion
-export type { AccountReviewProfile, AdminAccountsOperation, AdminAccountsPage, AdminBikeInterestRow, AdminBikeInventory, AdminBikeOperation, AdminBikeOperationResult, AdminBikeRental, AdminBikeType, AdminCampDocument, AdminCampSettings, AdminDocumentSignature, AdminGivebutterCatalog, AdminGivebutterCatalogOperation, AdminGivebutterWidgetOperation, AdminGivebutterWidgets, AdminImportOperation, AdminImportResult, AdminImportRow, AdminImportantDate, AdminImportantDateInput, AdminImportantDateOperation, AdminInterviewBooking, AdminMemberExportRow, AdminMemberInvite, AdminMemberOperation, AdminMemberRole, AdminMemberStatus, AdminNotificationPrefs, AdminPaymentOperation, AdminPaymentOperationResult, AdminPaymentSummary, AdminPaymentsPage, AdminScholarshipsPage, AdminShelter, AdminShelterOperation, AdminShift, AdminShiftType, AdminTicketRow, AdminWebhooksPage, Application, ApplicationActivityItem, ApplicationAdmin, ApplicationAnnotations, ApplicationCapacity, ApplicationCreatePayload, ApplicationCreateResponse, ApplicationNote, ApplicationScore, ApplicationStatus, ApplicationTransitionPayload, ApplicationTransitionResponse, ApplicationWorkflowInput, ApplicationWorkflowOptions, BikeRentalCatalogItem, BikeRentalCatalogResponse, BikeRentalDeliveryMode, BikeRentalFramePreference, BikeRentalInterestedMember, BikeRentalInterestedNotReservedResponse, BikeRentalRequestInput, BikeRentalRequestResult, BikeRentalReservation, BikeRentalReservationListResponse, BikeRentalWaiver, BookkeepingAdminOperation, BookkeepingExportPreview, BuildStrikeReportRow, CampDocumentDownloadUrl, CampDocumentSignature, CampDocumentSignaturesResponse, CampSettingsOperation, CampYearWithCounts, Commitment, CommitmentDataType, CommitmentValue, CommitmentsListResponse, ContactSyncResponse, ContractSection, CreateMeetingInput, CreateSapAssignmentInput, CreateScholarshipInput, DailyHeadcount, DashboardMetrics, DirectoryMember, DirectoryMembersListResponse, DocumentWriteInput, DuesStatus, DuesSummaryRow, DuesTypePayor, EmailCmsPreview, EmailComposerOptions, EmailDeliveryPage, EmailLog, EmailRecipient, EmailRecipientFilter, EmailRetry, EmailRetryCount, EmailRetryListResponse, EmailSegmentKey, EmailTemplate, ExchangeParams, ExchangeResult, ImageUploadTarget, ImportantDate, InterviewFeedBooking, ListingImage, LogisticsBreakdowns, LogisticsSummary, MarketplaceFlagReason, Meeting, MeetingDateOption, MeetingListResponse, MeetingRsvp, Member, MemberBikeStatus, MemberBootstrap, MemberCreatePayload, MemberCreateResponse, MemberCustomChecklistItem, MemberDashboard, MemberDeactivateResponse, MemberDevice, MemberDocumentPage, MemberDuesStatus, MemberGateId, MemberGatePlan, MemberGateStep, MemberInboxNotification, MemberInboxPage, MemberOnboardingUpdate, MemberPreferences, MemberProfileDetails, MemberPushPreferences, MemberRole, MemberSelfProfile, MemberSelfProfilePatch, MemberShelter, MemberShelterPage, MemberShiftView, MemberTag, MemberTagAssignment, MemberTagWithMemberCount, MemberUpdatePayload, MemberUpdateResponse, MobileShifts, NewListingInput, OnboardingChecklistCategory, OnboardingChecklistItem, OnboardingProgress, OrgConfig, OwnerShelterCreate, OwnerShelterPatch, PackingCampAdminItem, PackingCampAdminList, PackingCampCategory, PackingCampCategoryInput, PackingCampItem, PackingContainer, PackingContainerInput, PackingContainerListResponse, PackingContainerType, PackingItem, PackingItemStatus, PackingLayer, PackingListResponse, PackingPersonalItem, PackingPlacementListResponse, PaymentPageResponse, PublicMarketplaceClient, PublicMarketplaceClientOptions, RvAmperageTotal, SapAllocation, SapAssignment, SapDayAllocation, SchedulingAdminOperation, SchedulingAdminResult, SchedulingAdminSettings, SchedulingAvailability, SchedulingOverride, Scholarship, ScholarshipStats, ScholarshipStatus, SetPhotoPayload, SheetsSyncResult, ShelterTypeDistribution, Shift, ShiftAdminOperation, ShiftAdminOperationResult, ShiftAdminWorkflow, ShiftAdminWorkflowResult, ShiftPlannerData, ShiftSignup, ShiftType, SummerCampAttendee, SummerCampEvent, SummerCampRsvp, SummerCampRsvpInput, Ticket, TicketStatus, TicketUpdateInput, TshirtSizeTotal, UnmatchedRefund, UnsureDateMember, UpdateSapAllocationInput, UpdateSapAssignmentInput, UpsertPackingCampItemInput, UpsertSapDayAllocationInput, VehiclePass, VehiclePassStatus, VehiclePassUpdateInput, Waiver, WaiverContent, WaiverSection, WaiverSignPayload, WaiverSignResponse, WaiverStatus, WebhookCandidate, WebhookLog, WebhookMatchSelection };
+export type { AccountReviewProfile, AdminAccountsOperation, AdminAccountsPage, AdminBikeInterestRow, AdminBikeInventory, AdminBikeOperation, AdminBikeOperationResult, AdminBikeRental, AdminBikeType, AdminCampDocument, AdminCampSettings, AdminDocumentSignature, AdminGivebutterCatalog, AdminGivebutterCatalogOperation, AdminGivebutterWidgetOperation, AdminGivebutterWidgets, AdminImportOperation, AdminImportResult, AdminImportRow, AdminImportantDate, AdminImportantDateInput, AdminImportantDateOperation, AdminInterviewBooking, AdminMemberExportRow, AdminMemberInvite, AdminMemberOperation, AdminMemberRole, AdminMemberStatus, AdminNotificationPrefs, AdminPaymentOperation, AdminPaymentOperationResult, AdminPaymentSummary, AdminPaymentsPage, AdminScholarshipsPage, AdminShelter, AdminShelterOperation, AdminShift, AdminShiftType, AdminTicketRow, AdminWebhooksPage, Application, ApplicationActivityItem, ApplicationAdmin, ApplicationAnnotations, ApplicationCapacity, ApplicationCreatePayload, ApplicationCreateResponse, ApplicationEvent, ApplicationNote, ApplicationScore, ApplicationStatus, ApplicationTransitionPayload, ApplicationTransitionResponse, ApplicationWorkflowCapabilities, ApplicationWorkflowInput, ApplicationWorkflowOptions, AvailabilityWindow, BikeRentalCatalogItem, BikeRentalCatalogResponse, BikeRentalDeliveryMode, BikeRentalFramePreference, BikeRentalInterestedMember, BikeRentalInterestedNotReservedResponse, BikeRentalRequestInput, BikeRentalRequestResult, BikeRentalReservation, BikeRentalReservationListResponse, BikeRentalWaiver, BookkeepingAdminOperation, BookkeepingExportPreview, BookkeepingSummary, BuildStrikeReportRow, CampDocumentDownloadUrl, CampDocumentSignature, CampDocumentSignaturesResponse, CampSettingsOperation, CampYearWithCounts, Commitment, CommitmentDataType, CommitmentValue, CommitmentsListResponse, ContactSyncResponse, ContractSection, CreateMeetingInput, CreateSapAssignmentInput, CreateScholarshipInput, DailyHeadcount, DashboardMetrics, DirectoryMember, DirectoryMembersListResponse, DocumentWriteInput, DuesStatus, DuesSummaryRow, DuesTypePayor, EmailCmsPreview, EmailComposerOptions, EmailDeliveryPage, EmailLog, EmailRecipient, EmailRecipientFilter, EmailRetry, EmailRetryCount, EmailRetryListResponse, EmailSegmentKey, EmailTemplate, EventReadOnlyApiError, EventScopeParams, EventStatus, EventSummary, ExchangeParams, ExchangeResult, ImageUploadTarget, ImportantDate, InterviewFeedBooking, ListingImage, LogisticsBreakdowns, LogisticsSummary, MarketplaceFlagReason, Meeting, MeetingDateOption, MeetingListResponse, MeetingRsvp, Member, MemberBikeStatus, MemberBootstrap, MemberCreatePayload, MemberCreateResponse, MemberCustomChecklistItem, MemberDashboard, MemberDeactivateResponse, MemberDevice, MemberDocumentPage, MemberDuesStatus, MemberGateId, MemberGatePlan, MemberGateStep, MemberInboxNotification, MemberInboxPage, MemberOnboardingUpdate, MemberPaymentsOverview, MemberPreferences, MemberProfileDetails, MemberPushPreferences, MemberRole, MemberSelfProfile, MemberSelfProfilePatch, MemberShelter, MemberShelterPage, MemberShiftView, MemberTag, MemberTagAssignment, MemberTagWithMemberCount, MemberUpdatePayload, MemberUpdateResponse, MobileShifts, NewListingInput, OnboardingChecklistCategory, OnboardingChecklistItem, OnboardingProgress, OrgConfig, OrgEvent, OwnerShelterCreate, OwnerShelterPatch, PackingCampAdminItem, PackingCampAdminList, PackingCampCategory, PackingCampCategoryInput, PackingCampItem, PackingContainer, PackingContainerInput, PackingContainerListResponse, PackingContainerType, PackingItem, PackingItemStatus, PackingLayer, PackingListResponse, PackingPersonalItem, PackingPlacementListResponse, PaymentPageResponse, PublicMarketplaceClient, PublicMarketplaceClientOptions, RvAmperageTotal, SapAllocation, SapAssignment, SapDayAllocation, SchedulingAdminOperation, SchedulingAdminResult, SchedulingAdminSettings, SchedulingAvailability, SchedulingOverride, Scholarship, ScholarshipStats, ScholarshipStatus, SetPhotoPayload, SheetsSyncResult, ShelterTypeDistribution, Shift, ShiftAdminOperation, ShiftAdminOperationResult, ShiftAdminWorkflow, ShiftAdminWorkflowResult, ShiftPlannerData, ShiftSignup, ShiftType, SummerCampAttendee, SummerCampEvent, SummerCampRsvp, SummerCampRsvpInput, Ticket, TicketStatus, TicketUpdateInput, TshirtSizeTotal, UnmatchedRefund, UnsureDateMember, UpdateSapAllocationInput, UpdateSapAssignmentInput, UpsertPackingCampItemInput, UpsertSapDayAllocationInput, VehiclePass, VehiclePassStatus, VehiclePassUpdateInput, Waiver, WaiverContent, WaiverSection, WaiverSignPayload, WaiverSignResponse, WaiverStatus, WebhookCandidate, WebhookLog, WebhookMatchSelection };
 //# sourceMappingURL=index.d.ts.map