@ophelio/sdk 0.3.2 → 0.5.0

package/README.md

@@ -21,7 +21,10 @@ import { Ophelio } from '@ophelio/sdk'
 const ophelio = new Ophelio({ apiKey: process.env.OPHELIO_API_KEY })
 
 // Gate admission check
-const result = await ophelio.admit.check({ card: 'M-123456' })
+const result = await ophelio.admit.check({
+  card: 'M-123456',
+  targets: ['venue_a'], // where this gate is; optional
+})
 if (result.admitted) {
   console.log(result.pricing_group) // e.g. 'member_adult'
 }
@@ -136,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
@@ -156,8 +159,8 @@ Everything reachable with an API key is covered:
 
 | Namespace                       | Methods                                                                                                                                                                                                                                                                                                                                                                                      |
 | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `admit`                         | `check({ card })`                                                                                                                                                                                                                                                                                                                                                                            |
-| `members`                       | `sync({ since? })`, `get(id)`, `listEntitlements(id, { type? })`, `update(id, ...)`, `remove(id)`, `setPrimary(id)`, `reissueCard(id, { note? })`                                                                                                                                                                                                                                            |
+| `admit`                         | `check({ card, targets? })`                                                                                                                                                                                                                                                                                                                                                                  |
+| `members`                       | `sync({ since? })`, `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)`                                                                                                                                                                                                                                                                                       |
@@ -166,8 +169,8 @@ Everything reachable with an API key is covered:
 | `memberRoles`                   | `list()`, `get(id)`, `create(...)`, `update(id, ...)`, `delete(id)`                                                                                                                                                                                                                                                                                                                          |
 | `pricingGroups`                 | `list()`, `get(id)`, `create(...)`, `update(id, ...)`, `delete(id)`                                                                                                                                                                                                                                                                                                                          |
 | `salesChannels`                 | `list()`, `get(id)`, `create(...)`, `update(id, ...)`, `delete(id)`                                                                                                                                                                                                                                                                                                                          |
-| `targetCodes`                   | `list(params?)`, `get(id)`, `create(...)`, `update(id, ...)`, `delete(id)` — `update` takes `display_name` / `description` only; `code` is immutable                                                                                                                                                                                                                                         |
-| `calendars`                     | `list(params?)`, `get(id)`, `create(...)`, `update(id, ...)`, `delete(id)`, `listRules(id, params?)`, `createRule(id, ...)`                                                                                                                                                                                                                                                                  |
+| `targetCodes`                   | `list(params?)`, `get(id, params?)`, `create(...)`, `update(id, ...)`, `delete(id)` — `list`/`get` accept `view: 'full'` to include `plan_entitlement_count`; `update` takes `display_name` / `description` only, as `code` is immutable                                                                                                                                                     |
+| `calendars`                     | `list(params?)`, `get(id, params?)`, `create(...)`, `update(id, ...)`, `delete(id)`, `listRules(id, params?)`, `createRule(id, ...)` — `list`/`get` accept `view: 'full'` to include `plan_entitlement_count`                                                                                                                                                                                |
 | `calendarRules`                 | `get(id)`, `update(id, ...)`, `delete(id)`                                                                                                                                                                                                                                                                                                                                                   |
 | `planEntitlements`              | `get(id)`, `update(id, ...)`, `delete(id)`, `listAvailabilities(id, params?)`, `createAvailability(id, ...)`                                                                                                                                                                                                                                                                                 |
 | `planEntitlementAvailabilities` | `get(id)`, `update(id, ...)`, `delete(id)`                                                                                                                                                                                                                                                                                                                                                   |
@@ -183,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`),
@@ -194,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, {
@@ -205,18 +272,33 @@ 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
 
-The registered vocabulary of locations a gate reports (`venue_a`,
-`coffee_shop`). A `code` is lowercase letters and digits with single
+A registered code for each venue, zone, shop or gate that accepts
+memberships (`venue_a`, `coffee_shop`). Register each one once, then name it
+wherever a benefit is restricted, and wherever a request says where it is
+coming from. A `code` is lowercase letters and digits with single
 underscores between segments, at least one letter, 2–64 characters — and it is
 **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
@@ -247,10 +329,61 @@ 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 exist in the project's target code
-vocabulary — 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
+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.
+
+```ts
+const result = await ophelio.admit.check({
+  card: 'M-123456',
+  targets: ['venue_a', 'coffee_shop'],
+})
+
+result.target_context_applied // true — the entitlements were target-filtered
+
+for (const entitlement of result.entitlements) {
+  entitlement.valid_at // ['coffee_shop'] — where it is valid, when restricted
+  entitlement.valid_on // the date windows it matched, when restricted
+}
+```
 
-Availability rows can be authored today but nothing reads them yet, so they do
-not restrict admission.
+**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 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.cjs

@@ -248,12 +248,30 @@ function pageQuery(params) {
 //#endregion
 //#region src/resources/admit.ts
 var AdmitResource = class extends APIResource {
-	/** Gate admission check: `GET /admit?card=<cardId>`. */
+	/**
+	* Gate admission check: `GET /admit?card=<cardId>`.
+	*
+	* `targets` names the venue, zone, shop or gate the request is being made
+	* at, and is the context the entitlements are judged in — a benefit
+	* restricted to somewhere else drops out of `entitlements`. Three states,
+	* and they are answered differently: omit it and every target restriction
+	* is treated as satisfied; pass `[]` and only benefits valid anywhere
+	* survive; pass codes and a benefit needs one of them. Read
+	* `target_context_applied` on the result to tell the first apart from the
+	* other two.
+	*
+	* Codes are matched exactly, so send them back verbatim from
+	* `targetCodes.list()` — an unregistered or miscased code is refused with
+	* a 400 rather than quietly ignored.
+	*/
 	check(params, options) {
 		return this.transport.request({
 			method: "GET",
 			path: "/api/v1/admit",
-			query: { card: params.card },
+			query: {
+				card: params.card,
+				targets: params.targets
+			},
 			retryable: true,
 			options
 		});
@@ -329,7 +347,7 @@ var BillingOptionsResource = class extends APIResource {
 //#endregion
 //#region src/resources/calendar-rules.ts
 /**
-* A calendar rule is one row of a calendar's date vocabulary. Conditions AND
+* A calendar rule is one row of a calendar's set of dates. Conditions AND
 * within a rule and rules OR across a calendar, so "weekends in August" is a
 * single rule rather than two.
 *
@@ -367,17 +385,24 @@ var CalendarRulesResource = class extends APIResource {
 //#endregion
 //#region src/resources/calendars.ts
 /**
-* Calendars are named, reusable date vocabularies ("Peak 2026", "Weekends").
+* Calendars are named, reusable sets of dates ("Peak 2026", "Weekends").
 * The dates themselves live in the rules attached to them.
 *
 * A calendar containing no rules is valid for **all** dates, not none.
 */
 var CalendarsResource = class extends APIResource {
+	/**
+	* Pass `view: 'full'` to include `plan_entitlement_count` on every
+	* calendar.
+	*/
 	async list(params, options) {
 		const response = await this.transport.request({
 			method: "GET",
 			path: "/api/v1/calendars",
-			query: pageQuery(params),
+			query: {
+				...pageQuery(params),
+				...params?.view ? { view: params.view } : {}
+			},
 			retryable: true,
 			options
 		});
@@ -387,10 +412,14 @@ var CalendarsResource = class extends APIResource {
 			total_size: response.total_size
 		};
 	}
-	get(id, options) {
+	/**
+	* Pass `view: 'full'` to include `plan_entitlement_count`.
+	*/
+	get(id, params = {}, options) {
 		return this.transport.request({
 			method: "GET",
 			path: `/api/v1/calendars/${encodeURIComponent(id)}`,
+			query: params.view ? { view: params.view } : void 0,
 			retryable: true,
 			options
 		});
@@ -543,6 +572,14 @@ var EntitlementsResource = class extends APIResource {
 	/**
 	* Fire-and-forget batch usage reporting (one row per member). Idempotent
 	* per (key, member). Returns the recorded usage rows.
+	*
+	* `target` is the single registered code for the venue, zone, shop or gate
+	* the usage happened at — one event, one place, which is why it is
+	* singular here where the reads take `targets`. It is both the context the
+	* entitlement is judged in and a column on the row that comes back, so it
+	* is queryable in a way the free-form `context` is not. It is part of the
+	* idempotency fingerprint: a replay of the same key at a different target
+	* is refused rather than silently returning the original row.
 	*/
 	async recordUsage(params, options = {}) {
 		const { idempotencyKey, ...requestOptions } = options;
@@ -668,11 +705,29 @@ var MembersResource = class extends APIResource {
 			options
 		});
 	}
+	/**
+	* The entitlements a member can use right now.
+	*
+	* `targets` filters the result down to the benefits valid at the venue,
+	* zone, shop or gate it names — the same codes `admit.check` takes, but
+	* read as a filter here rather than as the context a gate decision is made
+	* in. Three states: omit it and nothing is filtered by target; pass `[]`
+	* and only benefits valid anywhere come back; pass codes and a benefit
+	* needs one of them. Codes are matched exactly, so send them back verbatim
+	* from `targetCodes.list()` — an unregistered one is refused with a 400.
+	*
+	* Each entitlement carries `valid_on` and `valid_at` when something
+	* restricts it by date or by target; both list only what it matched, never
+	* what it failed.
+	*/
 	async listEntitlements(id, params = {}, options) {
 		return (await this.transport.request({
 			method: "GET",
 			path: `/api/v1/members/${encodeURIComponent(id)}/entitlements`,
-			query: { type: params.type },
+			query: {
+				type: params.type,
+				targets: params.targets
+			},
 			retryable: true,
 			options
 		})).entitlements;
@@ -1257,16 +1312,23 @@ var SalesChannelsResource = class extends APIResource {
 //#endregion
 //#region src/resources/target-codes.ts
 /**
-* The registered vocabulary of locations a gate can report (`venue_a`,
-* `coffee_shop`). Codes are matched exactly — list them and send values back
-* verbatim rather than constructing or case-folding them.
+* The registered code for each venue, zone, shop or gate a request can name
+* (`venue_a`, `coffee_shop`). Codes are matched exactly — list them and send
+* values back verbatim rather than constructing or case-folding them.
 */
 var TargetCodesResource = class extends APIResource {
+	/**
+	* Pass `view: 'full'` to include `plan_entitlement_count` on every target
+	* code.
+	*/
 	async list(params, options) {
 		const response = await this.transport.request({
 			method: "GET",
 			path: "/api/v1/target-codes",
-			query: pageQuery(params),
+			query: {
+				...pageQuery(params),
+				...params?.view ? { view: params.view } : {}
+			},
 			retryable: true,
 			options
 		});
@@ -1276,10 +1338,14 @@ var TargetCodesResource = class extends APIResource {
 			total_size: response.total_size
 		};
 	}
-	get(id, options) {
+	/**
+	* Pass `view: 'full'` to include `plan_entitlement_count`.
+	*/
+	get(id, params = {}, options) {
 		return this.transport.request({
 			method: "GET",
 			path: `/api/v1/target-codes/${encodeURIComponent(id)}`,
+			query: params.view ? { view: params.view } : void 0,
 			retryable: true,
 			options
 		});