@ophelio/sdk 0.4.0 → 0.5.0

package/README.md

@@ -139,11 +139,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
@@ -186,6 +186,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 +261,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 +272,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 +297,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,15 +329,16 @@ 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
+checked against the availability rows for that place. `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.
@@ -279,29 +357,33 @@ 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.** 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. `members.sync` takes no targets at all — each member's entitlements
+are a snapshot taken at the moment of the sync, and the gate that caches them
+applies no rules of its own.
+
+`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 every read to say where it is. Once all of its gates send
+their own `targets`, an operator turns the setting on, and from then on a read
+that omits `targets` altogether is refused with a 400. 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.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: {

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

package/package.json

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