@ophelio/sdk 0.3.2 → 0.4.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'
 }
@@ -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)`                                                                                                                                                                                                                                                                                                                                                   |
@@ -209,8 +212,10 @@ A calendar containing no rules is valid for **all** dates, not none.
 
 ### 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.
@@ -249,8 +254,54 @@ 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.
+Every code in `targets` must already be registered as a target code — an
+unregistered one is rejected, never registered on the fly.
+
+### 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.
+
+```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 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.
+
+**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.

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
 		});