@ophelio/sdk 0.4.0 → 0.5.1

package/README.md

@@ -30,9 +30,11 @@ if (result.admitted) {
 }
 
 // Offline gate cache
-const { members, generated_at } = await ophelio.members.sync()
+const { members, generated_at } = await ophelio.members.sync({
+  targets: ['venue_a'], // roster for this gate; optional
+})
 // later, incremental:
-await ophelio.members.sync({ since: generated_at })
+await ophelio.members.sync({ since: generated_at, targets: ['venue_a'] })
 ```
 
 ## Authentication
@@ -139,11 +141,11 @@ for await (const change of paginate((page) =>
   // …
 }
 
-// or drain everything into an array (loads the whole collection into memory):
+// or load everything into one array (holds the whole collection in memory):
 const customers = await collect((page) => ophelio.customers.list(page))
 ```
 
-To page manually — e.g. to surface `total_size` or drive numbered pages — feed
+To page manually — for example to show `total_size` or build numbered pages — feed
 `next_page_token` back in as `page_token` until it comes back empty.
 
 `page_size` defaults to 50 and is capped at 250. Because pagination is
@@ -160,7 +162,7 @@ Everything reachable with an API key is covered:
 | Namespace                       | Methods                                                                                                                                                                                                                                                                                                                                                                                      |
 | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `admit`                         | `check({ card, targets? })`                                                                                                                                                                                                                                                                                                                                                                  |
-| `members`                       | `sync({ since? })`, `get(id)`, `listEntitlements(id, { type?, targets? })`, `update(id, ...)`, `remove(id)`, `setPrimary(id)`, `reissueCard(id, { note? })`                                                                                                                                                                                                                                  |
+| `members`                       | `sync({ since?, targets? })`, `get(id)`, `listEntitlements(id, { type?, targets? })`, `update(id, ...)`, `remove(id)`, `setPrimary(id)`, `reissueCard(id, { note? })`                                                                                                                                                                                                                        |
 | `memberships`                   | `list(params?)`, `get(id)`, `create(...)`, `update(id, ...)`, `cancel(id, ...)`, `uncancel(id)`, `renew(id, ...)`, `upgrade(id, ...)`, `downgrade(id, ...)`, `listMembers(id)`, `addMember(id, ...)`, `listScheduledChanges(id, params?)`, `cancelScheduledChange(id, changeId)`, `listTransactions(id, params?)`, `listTermTransactions(id, termId, params?)`, `createTransaction(id, ...)` |
 | `customers`                     | `list(params?)`, `get(id, params?)`, `create(...)`, `update(id, ...)`, `delete(id)`, `listMemberships(id, params?)` — `list`/`get` accept `view: 'full'` to include `membership_summary`                                                                                                                                                                                                     |
 | `entitlements`                  | `redeem(...)`, `recordUsage(...)`, `list()`, `get(id)`, `create(...)`, `update(id, ...)`, `delete(id)`                                                                                                                                                                                                                                                                                       |
@@ -186,6 +188,70 @@ Every method accepts a trailing `options` argument: `{ signal?, headers? }`
 Endpoints requiring a user session (API key management, organisation and
 project admin) are intentionally not in the SDK — API keys cannot call them.
 
+### Admission
+
+`admit.check` admits a member who has free entry they can use **here and
+now**. `admitted` comes back `true` only when the member holds a `free_entry`
+entitlement that passes all three checks: the membership's status still allows
+it; if the membership is in its grace period, the entitlement has
+`active_during_grace` set; and no availability row rules it out for the date
+and place of the request — an entitlement with no rows applies everywhere and
+always, and one that has rows needs just one of them to match. An active
+membership on its own is not enough.
+
+```ts
+const result = await ophelio.admit.check({ card: 'M-123456' })
+
+if (result.admitted) {
+  console.log(result.pricing_group) // 'member_adult' — price the ticket
+} else if (
+  result.deny_reason === 'free_entry_not_granted' ||
+  result.deny_reason === 'free_entry_unavailable'
+) {
+  result.entitlements // still populated — discounts, guest passes, early access
+  result.pricing_group // still resolved — prices the ticket at the member rate
+}
+```
+
+Two results of that rule are deliberate, and you will meet both on a default
+configuration:
+
+- A membership in its **grace period** is not admitted unless its free entry
+  has `active_during_grace` set. A grace period is time to renew, not
+  permission to enter. The denial reads `free_entry_unavailable`.
+- A plan with **no free-entry entitlement** never admits anyone. It still
+  works for discounts, guest passes and early access — a benefits-only plan.
+
+The two cases have separate deny reasons, because staff act on them
+differently:
+
+| `deny_reason`            | Meaning                                                                                                                                                                                                                                                     |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `free_entry_not_granted` | The plan grants no free entry at all. Permanent — no operator action changes it, so do not alert on it.                                                                                                                                                     |
+| `free_entry_unavailable` | The plan grants free entry, but it is not usable for this request: no availability row covers this date or this target, or the membership is in its grace period and its free entry does not have `active_during_grace` set. May stop happening on its own. |
+
+`free_entry_unavailable` is the one worth monitoring: a calendar nobody rolled
+over to the new year turns away a whole plan at once and shows up as this
+reason. It also covers the everyday grace-period case above, so alert on a rise
+in how often it happens rather than on the reason itself.
+
+Only these two free-entry denials return the member's remaining `entitlements`
+and their `pricing_group`, because a visitor who has benefits but not free
+entry is usually about to buy a ticket at the desk. Every other denial —
+`card_not_found`, `member_removed`, `membership_expired`,
+`membership_cancelled`, `membership_incomplete` and `payment_overdue` —
+returns an empty `entitlements` list and a `null` `pricing_group`. If you build
+a desk screen that offers the member their benefits, drive it from the two
+free-entry denials only. The `renew_at_desk` action is separate again: it
+depends on the membership's status, not on whether the member was admitted, so
+it can appear on an admitted response too.
+
+`members.sync` returns **more** members than `admit.check` would admit, and
+that is deliberate: a benefits-only member is turned away at the gate but still
+has discounts and guest passes an offline till needs. An offline gate reaches
+the same answer by reading each cached member's `entitlements` — if free entry
+is in the list, admit — and applies no rules of its own.
+
 ### Calendar rules
 
 `date_from` and `date_until` are **timezone-free calendar dates** (`YYYY-MM-DD`),
@@ -197,8 +263,8 @@ open-ended on that side.
 JavaScript's `Date.prototype.getDay()` calls Sunday 0). An empty array means
 every day.
 
-Conditions AND within a rule and rules OR across a calendar, so "weekends in
-August" is a single rule:
+A date has to satisfy every condition in a rule, and a calendar matches a date
+if any one of its rules does. So "weekends in August" is a single rule:
 
 ```ts
 await ophelio.calendars.createRule(calendar.id, {
@@ -208,7 +274,20 @@ await ophelio.calendars.createRule(calendar.id, {
 })
 ```
 
-A calendar containing no rules is valid for **all** dates, not none.
+A calendar with no rules matches **every** date, not none: a half-finished
+calendar lets everyone through rather than quietly turning members away. You
+cannot reach that state through the API, because three requests are refused:
+
+- A rule has to restrict something. One that sets neither `date_from` nor
+  `date_until` nor a weekday is refused with a **400**.
+- A calendar with no rules cannot be attached to a plan entitlement, whether an
+  availability row is being created with it or an existing row repointed to it.
+  Attaching one is refused with a **409**, because a row that restricts no
+  dates would make the entitlement valid on every date, no matter what the
+  other rows say.
+- The last rule of a calendar that is in use cannot be deleted. Deleting it is
+  refused with a **409** that says how many plan entitlements use the calendar.
+  Add the replacement rule first, then delete.
 
 ### Target codes
 
@@ -220,8 +299,8 @@ underscores between segments, at least one letter, 2–64 characters — and it
 **matched exactly**. A miscased code is an unregistered code, so send values
 back verbatim from `list()` rather than constructing or case-folding them.
 
-A code outside the grammar is **rejected, never transformed**: `Venue A` comes
-back as a 400, not as a stored `venue_a`.
+A code that does not match that format is **rejected, never corrected for
+you**: `Venue A` comes back as a 400, rather than being stored as `venue_a`.
 
 `code` is **immutable from creation**; `display_name` and `description` stay
 editable forever. `UpdateTargetCodeParams` therefore has no `code` field, so a
@@ -252,18 +331,20 @@ await ophelio.planEntitlements.createAvailability(planEntitlement.id, {
 })
 ```
 
-Rows **OR**, and the absence of rows is judged **per plan entitlement**: a plan
-entitlement with no rows at all is unrestricted, never restricted to nothing.
-Every code in `targets` must already be registered as a target code — an
-unregistered one is rejected, never registered on the fly.
+A plan entitlement applies if **any one** of its rows matches. Having no rows
+is decided for each plan entitlement on its own: an entitlement with no rows
+applies on every date and in every place, rather than nowhere. Every code in
+`targets` must already be registered as a target code — an unregistered one is
+rejected, not registered for you.
 
 ### Target context
 
 A read can say where it is being made, and the entitlements it gets back are
-judged against the availability rows in that light. `admit.check` and
-`members.listEntitlements` take `targets` — a set of registered target codes,
-sent comma-separated on the wire — and `entitlements.recordUsage` takes a
-singular `target`, because one usage event happens at one place.
+checked against the availability rows for that place. `admit.check`,
+`members.listEntitlements` and `members.sync` take `targets` — a set of
+registered target codes, sent comma-separated on the wire — and
+`entitlements.recordUsage` takes a singular `target`, because one usage event
+happens at one place.
 
 ```ts
 const result = await ophelio.admit.check({
@@ -279,29 +360,46 @@ for (const entitlement of result.entitlements) {
 }
 ```
 
-**Three states, answered differently.** Omitting `targets` is the permissive
-default: every target restriction is treated as satisfied, and
-`target_context_applied` comes back `false`. Passing `[]` says the caller is
-naming no targets, so only benefits valid anywhere survive. Passing codes
-means a benefit needs one of them. Dates are enforced in all three.
+**Three cases, answered differently on `admit.check` and
+`members.listEntitlements`.** Omitting `targets` says nothing about where the
+request is: every target restriction is then treated as met, and
+`target_context_applied` comes back `false`. Passing `[]` says the caller names
+no targets, so only benefits valid everywhere come back. Passing codes means a
+benefit has to name one of them. Dates are checked in all three cases.
 
 **Codes are matched exactly.** Send them back verbatim from
 `targetCodes.list()`; an unregistered or miscased code is refused with a 400
 rather than dropped, so a typo cannot pass for a benefit that does not apply.
 
-**The parameter means something different on each surface.** At the gate it is
-the context the decision is made in; on `members.listEntitlements` it is a
-filter over the result. `members.sync` takes no target context at all — the
-offline roster carries each member's entitlements as at the moment of sync,
-and the gate that caches it evaluates no rules of its own.
-
-`valid_on` and `valid_at` carry only what an entitlement **matched**, and are
-omitted entirely when nothing restricts it on that axis. What it failed is
-never returned: the response says where and when a benefit is valid, never
-which restrictions the member did not satisfy. Because rows OR, the two read
-as independent unions rather than as pairs.
-
-A project can require target context — once every gate reports its own, it is
-turned on and a read that says nothing about where it is is refused from then
-on. It is a per-project setting rather than anything the client sends, so roll
-out sending `targets` before expecting it to be enforced.
+**The parameter does a different job on each endpoint.** At the gate it is part
+of the admission decision; on `members.listEntitlements` it filters the list you
+get back. On `members.sync` it is the scope of what one gate stores for later:
+each member's entitlements are a snapshot taken at the moment of the sync, read
+back during an outage without being checked again, so the targets you sync with
+settle what that gate can grant while it is offline. The gate applies no rules
+of its own.
+
+**`members.sync` differs from the other two in two ways, both deliberate.** An
+empty `targets` is refused with a 400 there. It is not read as naming no
+targets, so it never returns only the benefits valid everywhere. And the
+per-project setting below does not apply to it — a sync that omits `targets`
+is always answered and returns the whole roster. The roster is the copy a gate
+falls back on when it cannot reach us, so a quietly shortened or unfetchable
+one would go unnoticed until the outage it exists for. Neither is an oversight
+to be tidied up into consistency.
+
+`valid_on` and `valid_at` list only what an entitlement **matched**. `valid_on`
+is omitted when no date restricts it, and `valid_at` when no place does. What
+it failed to match is never returned: the response says where and when a
+benefit is valid, never which restrictions the member missed. Read the two
+lists separately — because an entitlement applies if any one row matches, a
+date in `valid_on` and a place in `valid_at` need not come from the same row.
+
+A project can require `admit.check` and `members.listEntitlements` to say where
+they are. Once all of its gates send their own `targets`, an operator turns the
+setting on, and from then on one of those reads that omits `targets` altogether
+is refused with a 400. `members.sync` is exempt, as above. Passing `[]` is not
+the same as omitting it: that read has said where it is and named no targets,
+so it is still answered, exactly as the three cases above describe. It is a
+per-project setting rather than anything the client sends, so start sending
+`targets` before expecting it to be required.

package/dist/index.cjs

@@ -687,12 +687,31 @@ var MembersResource = class extends APIResource {
 	/**
 	* Active-member list for offline gate caching. Pass the previous
 	* response's `generated_at` as `since` to fetch incrementally.
+	*
+	* `targets` names the venue, zone, shop or gate this roster is for, and
+	* settles what the gate can grant while it is offline: each member's
+	* entitlements are stored as they stand at the moment of the sync and are
+	* read back during an outage without being checked again. Omit it for the
+	* whole roster. Codes are matched exactly, so send them back verbatim from
+	* `targetCodes.list()` — an unregistered one is refused with a 400.
+	*
+	* Two things work differently here than on `admit.check` and
+	* `members.listEntitlements`, both on purpose. An empty `targets` is
+	* refused with a 400. It is not read as naming no targets, so it never
+	* returns only the benefits valid everywhere. And a project that requires
+	* every read to say where it is still answers a sync that omits `targets`.
+	* The roster is what a gate falls back on when it cannot reach us, so a
+	* quietly shortened or unfetchable copy would only show up during the
+	* outage it was kept for.
 	*/
 	sync(params = {}, options) {
 		return this.transport.request({
 			method: "GET",
 			path: "/api/v1/members/sync",
-			query: { since: params.since },
+			query: {
+				since: params.since,
+				targets: params.targets
+			},
 			retryable: true,
 			options
 		});

package/dist/index.d.cts

@@ -1652,7 +1652,7 @@ interface components {
         reason: string;
       })[];
       admitted: boolean; /** @enum {string|null} */
-      deny_reason: "card_not_found" | "member_removed" | "membership_cancelled" | "membership_expired" | "membership_incomplete" | "payment_overdue" | null;
+      deny_reason: "card_not_found" | "free_entry_not_granted" | "free_entry_unavailable" | "member_removed" | "membership_cancelled" | "membership_expired" | "membership_incomplete" | "payment_overdue" | null;
       member: components["schemas"]["AdmitMember"] | null;
       membership_id: string | null; /** @enum {string|null} */
       membership_status: "active" | "cancelled" | "expired" | "grace_period" | "incomplete" | "past_due" | null;
@@ -3329,6 +3329,14 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   PlanEntitlementAvailabilitiesController_get: {
@@ -3422,6 +3430,14 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   PlanPricingGroupMappingsController_delete: {
@@ -3671,6 +3687,7 @@ interface operations {
   MembersController_sync: {
     parameters: {
       query?: {
+        /** @description Registered target codes of the place this roster is for, sent comma-separated (`?targets=venue_a,coffee_shop`). Each member's entitlements are then narrowed to those usable there. Codes are matched exactly; an unregistered code is refused. Omit the parameter to receive the whole roster, with entitlements narrowed by date alone. Sending it with nothing in it (`?targets=`) is an error here, unlike on `GET /admit` and `GET /members/:id/entitlements`, where it means the caller named no place: this roster is used during an outage without being checked again, so an empty value would leave a gate short of entitlements it would not discover until the outage it kept the roster for. */targets?: string[];
         since?: string;
       };
       header?: never;
@@ -3687,6 +3704,14 @@ interface operations {
           "application/json": components["schemas"]["MemberSyncResponse"];
         };
       };
+      400: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   MembersController_get: {
@@ -4768,6 +4793,14 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   CalendarRulesController_update: {
@@ -5855,9 +5888,26 @@ declare class MembersResource extends APIResource {
   /**
    * Active-member list for offline gate caching. Pass the previous
    * response's `generated_at` as `since` to fetch incrementally.
+   *
+   * `targets` names the venue, zone, shop or gate this roster is for, and
+   * settles what the gate can grant while it is offline: each member's
+   * entitlements are stored as they stand at the moment of the sync and are
+   * read back during an outage without being checked again. Omit it for the
+   * whole roster. Codes are matched exactly, so send them back verbatim from
+   * `targetCodes.list()` — an unregistered one is refused with a 400.
+   *
+   * Two things work differently here than on `admit.check` and
+   * `members.listEntitlements`, both on purpose. An empty `targets` is
+   * refused with a 400. It is not read as naming no targets, so it never
+   * returns only the benefits valid everywhere. And a project that requires
+   * every read to say where it is still answers a sync that omits `targets`.
+   * The roster is what a gate falls back on when it cannot reach us, so a
+   * quietly shortened or unfetchable copy would only show up during the
+   * outage it was kept for.
    */
   sync(params?: {
     since?: string;
+    targets?: string[];
   }, options?: RequestOptions): Promise<MemberSyncResponse>;
   get(id: string, options?: RequestOptions): Promise<Member>;
   /**

package/dist/index.d.mts

@@ -1652,7 +1652,7 @@ interface components {
         reason: string;
       })[];
       admitted: boolean; /** @enum {string|null} */
-      deny_reason: "card_not_found" | "member_removed" | "membership_cancelled" | "membership_expired" | "membership_incomplete" | "payment_overdue" | null;
+      deny_reason: "card_not_found" | "free_entry_not_granted" | "free_entry_unavailable" | "member_removed" | "membership_cancelled" | "membership_expired" | "membership_incomplete" | "payment_overdue" | null;
       member: components["schemas"]["AdmitMember"] | null;
       membership_id: string | null; /** @enum {string|null} */
       membership_status: "active" | "cancelled" | "expired" | "grace_period" | "incomplete" | "past_due" | null;
@@ -3329,6 +3329,14 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   PlanEntitlementAvailabilitiesController_get: {
@@ -3422,6 +3430,14 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   PlanPricingGroupMappingsController_delete: {
@@ -3671,6 +3687,7 @@ interface operations {
   MembersController_sync: {
     parameters: {
       query?: {
+        /** @description Registered target codes of the place this roster is for, sent comma-separated (`?targets=venue_a,coffee_shop`). Each member's entitlements are then narrowed to those usable there. Codes are matched exactly; an unregistered code is refused. Omit the parameter to receive the whole roster, with entitlements narrowed by date alone. Sending it with nothing in it (`?targets=`) is an error here, unlike on `GET /admit` and `GET /members/:id/entitlements`, where it means the caller named no place: this roster is used during an outage without being checked again, so an empty value would leave a gate short of entitlements it would not discover until the outage it kept the roster for. */targets?: string[];
         since?: string;
       };
       header?: never;
@@ -3687,6 +3704,14 @@ interface operations {
           "application/json": components["schemas"]["MemberSyncResponse"];
         };
       };
+      400: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   MembersController_get: {
@@ -4768,6 +4793,14 @@ interface operations {
           "application/json": components["schemas"]["ErrorResponse"];
         };
       };
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
     };
   };
   CalendarRulesController_update: {
@@ -5855,9 +5888,26 @@ declare class MembersResource extends APIResource {
   /**
    * Active-member list for offline gate caching. Pass the previous
    * response's `generated_at` as `since` to fetch incrementally.
+   *
+   * `targets` names the venue, zone, shop or gate this roster is for, and
+   * settles what the gate can grant while it is offline: each member's
+   * entitlements are stored as they stand at the moment of the sync and are
+   * read back during an outage without being checked again. Omit it for the
+   * whole roster. Codes are matched exactly, so send them back verbatim from
+   * `targetCodes.list()` — an unregistered one is refused with a 400.
+   *
+   * Two things work differently here than on `admit.check` and
+   * `members.listEntitlements`, both on purpose. An empty `targets` is
+   * refused with a 400. It is not read as naming no targets, so it never
+   * returns only the benefits valid everywhere. And a project that requires
+   * every read to say where it is still answers a sync that omits `targets`.
+   * The roster is what a gate falls back on when it cannot reach us, so a
+   * quietly shortened or unfetchable copy would only show up during the
+   * outage it was kept for.
    */
   sync(params?: {
     since?: string;
+    targets?: string[];
   }, options?: RequestOptions): Promise<MemberSyncResponse>;
   get(id: string, options?: RequestOptions): Promise<Member>;
   /**

package/dist/index.mjs

@@ -686,12 +686,31 @@ var MembersResource = class extends APIResource {
 	/**
 	* Active-member list for offline gate caching. Pass the previous
 	* response's `generated_at` as `since` to fetch incrementally.
+	*
+	* `targets` names the venue, zone, shop or gate this roster is for, and
+	* settles what the gate can grant while it is offline: each member's
+	* entitlements are stored as they stand at the moment of the sync and are
+	* read back during an outage without being checked again. Omit it for the
+	* whole roster. Codes are matched exactly, so send them back verbatim from
+	* `targetCodes.list()` — an unregistered one is refused with a 400.
+	*
+	* Two things work differently here than on `admit.check` and
+	* `members.listEntitlements`, both on purpose. An empty `targets` is
+	* refused with a 400. It is not read as naming no targets, so it never
+	* returns only the benefits valid everywhere. And a project that requires
+	* every read to say where it is still answers a sync that omits `targets`.
+	* The roster is what a gate falls back on when it cannot reach us, so a
+	* quietly shortened or unfetchable copy would only show up during the
+	* outage it was kept for.
 	*/
 	sync(params = {}, options) {
 		return this.transport.request({
 			method: "GET",
 			path: "/api/v1/members/sync",
-			query: { since: params.since },
+			query: {
+				since: params.since,
+				targets: params.targets
+			},
 			retryable: true,
 			options
 		});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ophelio/sdk",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Official JavaScript / TypeScript SDK for the Ophel.io membership & entitlement API.",
   "license": "MIT",
   "author": "Ophel.io",