@ophelio/sdk 0.3.1 → 0.4.0

package/dist/index.mjs

@@ -125,6 +125,21 @@ const DEFAULT_MAX_RETRIES = 2;
 function resolveIdempotencyKey(idempotencyKey) {
 	return idempotencyKey?.trim() || crypto.randomUUID();
 }
+/**
+* Serialises query parameters into a search string.
+*
+* `undefined` drops the parameter entirely. An empty array does not: it emits
+* the bare key (`?status=`), because "filter by nothing" and "do not filter"
+* are different requests and the API distinguishes them.
+*/
+function serialiseQuery(query) {
+	const search = new URLSearchParams();
+	for (const [key, value] of Object.entries(query ?? {})) {
+		if (value === void 0) continue;
+		search.set(key, Array.isArray(value) ? value.join(",") : value);
+	}
+	return search.toString();
+}
 var Transport = class {
 	apiKey;
 	baseUrl;
@@ -179,9 +194,7 @@ var Transport = class {
 		throw lastError;
 	}
 	buildUrl(params) {
-		const search = new URLSearchParams();
-		for (const [key, value] of Object.entries(params.query ?? {})) if (value !== void 0) search.set(key, value);
-		const queryString = search.toString();
+		const queryString = serialiseQuery(params.query);
 		return `${this.baseUrl}${params.path}${queryString ? `?${queryString}` : ""}`;
 	}
 	buildHeaders(params) {
@@ -234,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
 		});
@@ -315,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.
 *
@@ -353,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
 		});
@@ -373,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
 		});
@@ -529,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;
@@ -654,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;
@@ -917,6 +985,45 @@ var MembershipsResource = class extends APIResource {
 	}
 };
 //#endregion
+//#region src/resources/plan-entitlement-availabilities.ts
+/**
+* An availability row says when and where one plan entitlement applies: a
+* calendar (null = any date) and a set of registered target codes (empty =
+* anywhere). Rows OR, and a plan entitlement with no rows at all is
+* unrestricted.
+*
+* Rows are created and listed through their plan entitlement
+* (`ophelio.planEntitlements.createAvailability` / `listAvailabilities`); this
+* resource addresses an individual row.
+*/
+var PlanEntitlementAvailabilitiesResource = class extends APIResource {
+	get(id, options) {
+		return this.transport.request({
+			method: "GET",
+			path: `/api/v1/plan-entitlement-availabilities/${encodeURIComponent(id)}`,
+			retryable: true,
+			options
+		});
+	}
+	update(id, params, options) {
+		return this.transport.request({
+			method: "PATCH",
+			path: `/api/v1/plan-entitlement-availabilities/${encodeURIComponent(id)}`,
+			body: params,
+			retryable: false,
+			options
+		});
+	}
+	async delete(id, options) {
+		await this.transport.request({
+			method: "DELETE",
+			path: `/api/v1/plan-entitlement-availabilities/${encodeURIComponent(id)}`,
+			retryable: false,
+			options
+		});
+	}
+};
+//#endregion
 //#region src/resources/plan-entitlements.ts
 var PlanEntitlementsResource = class extends APIResource {
 	get(id, options) {
@@ -945,6 +1052,29 @@ var PlanEntitlementsResource = class extends APIResource {
 			options
 		});
 	}
+	async listAvailabilities(id, params, options) {
+		const response = await this.transport.request({
+			method: "GET",
+			path: `/api/v1/plan-entitlements/${encodeURIComponent(id)}/availabilities`,
+			query: pageQuery(params),
+			retryable: true,
+			options
+		});
+		return {
+			items: response.availabilities,
+			next_page_token: response.next_page_token,
+			total_size: response.total_size
+		};
+	}
+	createAvailability(id, params, options) {
+		return this.transport.request({
+			method: "POST",
+			path: `/api/v1/plan-entitlements/${encodeURIComponent(id)}/availabilities`,
+			body: params,
+			retryable: false,
+			options
+		});
+	}
 };
 //#endregion
 //#region src/resources/plan-links.ts
@@ -1181,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
 		});
@@ -1200,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
 		});
@@ -1375,6 +1516,7 @@ var Ophelio = class Ophelio {
 	calendars;
 	calendarRules;
 	planEntitlements;
+	planEntitlementAvailabilities;
 	planLinks;
 	planPricingGroupMappings;
 	billingOptionSalesChannels;
@@ -1401,6 +1543,7 @@ var Ophelio = class Ophelio {
 		this.calendars = new CalendarsResource(transport);
 		this.calendarRules = new CalendarRulesResource(transport);
 		this.planEntitlements = new PlanEntitlementsResource(transport);
+		this.planEntitlementAvailabilities = new PlanEntitlementAvailabilitiesResource(transport);
 		this.planLinks = new PlanLinksResource(transport);
 		this.planPricingGroupMappings = new PlanPricingGroupMappingsResource(transport);
 		this.billingOptionSalesChannels = new BillingOptionSalesChannelsResource(transport);

package/package.json

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