@ophelio/sdk 0.3.2 → 0.5.0

package/dist/index.mjs

@@ -247,12 +247,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
 		});
@@ -328,7 +346,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.
 *
@@ -366,17 +384,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
 		});
@@ -386,10 +411,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
 		});
@@ -542,6 +571,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;
@@ -667,11 +704,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;
@@ -1256,16 +1311,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
 		});
@@ -1275,10 +1337,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
 		});

package/package.json

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