@ophelio/sdk 0.3.0 → 0.3.2

package/README.md

@@ -146,30 +146,35 @@ To page manually — e.g. to surface `total_size` or drive numbered pages — fe
 `page_size` defaults to 50 and is capped at 250. Because pagination is
 offset-based, a row can be seen twice or skipped across a page boundary if the
 collection is written to while you iterate. Paginated methods are marked
-`(params?)` in the table below; the bounded lists (config resources,
-`listMembers`) return a plain array.
+`(params?)` in the table below; every other list — the bounded ones such as
+member roles, pricing groups, sales channels, entitlements, plans and
+`listMembers` — returns a plain array.
 
 ## API surface
 
 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? })`                                                                                                                                                                                                                                            |
-| `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)`                                                                                                                                                                                                                                                                                       |
-| `plans`                      | `list()`, `get(id)`, `create(...)`, `update(id, ...)`, `delete(id)`, `listBillingOptions(id)`, `createBillingOption(id, ...)`, `listEntitlements(id)`, `createEntitlement(id, ...)`, `listPlanLinks(id)`, `createPlanLink(id, ...)`, `listPricingGroupMappings(id)`, `createPricingGroupMapping(id, ...)`                                                                                    |
-| `billingOptions`             | `list()`, `get(id)`, `update(id, ...)`, `delete(id)`, `listSalesChannels(id)`, `createSalesChannelLink(id, ...)`                                                                                                                                                                                                                                                                             |
-| `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)`                                                                                                                                                                                                                                                                                                                          |
-| `planEntitlements`           | `get(id)`, `update(id, ...)`, `delete(id)`                                                                                                                                                                                                                                                                                                                                                   |
-| `planLinks`                  | `delete(id)`                                                                                                                                                                                                                                                                                                                                                                                 |
-| `planPricingGroupMappings`   | `delete(id)`                                                                                                                                                                                                                                                                                                                                                                                 |
-| `billingOptionSalesChannels` | `delete(id)`                                                                                                                                                                                                                                                                                                                                                                                 |
-| `webhookSubscriptions`       | `list()`, `get(id)`, `create(...)`, `update(id, ...)`, `delete(id)`, `listDeliveries(id, params?)`                                                                                                                                                                                                                                                                                           |
+| Namespace                       | Methods                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `admit`                         | `check({ card })`                                                                                                                                                                                                                                                                                                                                                                            |
+| `members`                       | `sync({ since? })`, `get(id)`, `listEntitlements(id, { type? })`, `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)`                                                                                                                                                                                                                                                                                       |
+| `plans`                         | `list()`, `get(id)`, `create(...)`, `update(id, ...)`, `delete(id)`, `listBillingOptions(id)`, `createBillingOption(id, ...)`, `listEntitlements(id)`, `createEntitlement(id, ...)`, `listPlanLinks(id)`, `createPlanLink(id, ...)`, `listPricingGroupMappings(id)`, `createPricingGroupMapping(id, ...)`                                                                                    |
+| `billingOptions`                | `list()`, `get(id)`, `update(id, ...)`, `delete(id)`, `listSalesChannels(id)`, `createSalesChannelLink(id, ...)`                                                                                                                                                                                                                                                                             |
+| `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, ...)`                                                                                                                                                                                                                                                                  |
+| `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)`                                                                                                                                                                                                                                                                                                                                                   |
+| `planLinks`                     | `delete(id)`                                                                                                                                                                                                                                                                                                                                                                                 |
+| `planPricingGroupMappings`      | `delete(id)`                                                                                                                                                                                                                                                                                                                                                                                 |
+| `billingOptionSalesChannels`    | `delete(id)`                                                                                                                                                                                                                                                                                                                                                                                 |
+| `webhookSubscriptions`          | `list()`, `get(id)`, `create(...)`, `update(id, ...)`, `delete(id)`, `listDeliveries(id, params?)`                                                                                                                                                                                                                                                                                           |
 
 Every method accepts a trailing `options` argument: `{ signal?, headers? }`
 (plus `idempotencyKey?` on the idempotency-keyed mutations: `memberships.create`
@@ -177,3 +182,75 @@ 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.
+
+### Calendar rules
+
+`date_from` and `date_until` are **timezone-free calendar dates** (`YYYY-MM-DD`),
+never instants — an ISO timestamp is rejected. `date_until` is **inclusive**:
+`'2026-08-31'` covers the whole of 31 August. Both are nullable, meaning
+open-ended on that side.
+
+`days_of_week` uses **ISO-8601 numbering: 1 = Monday … 7 = Sunday** (note that
+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:
+
+```ts
+await ophelio.calendars.createRule(calendar.id, {
+  date_from: '2026-08-01',
+  date_until: '2026-08-31',
+  days_of_week: [6, 7],
+})
+```
+
+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
+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`.
+
+`code` is **immutable from creation**; `display_name` and `description` stay
+editable forever. `UpdateTargetCodeParams` therefore has no `code` field, so a
+rename fails to type-check before it can fail with a 400:
+
+```ts
+const venue = await ophelio.targetCodes.create({
+  code: 'venue_a',
+  display_name: 'Venue A',
+})
+
+await ophelio.targetCodes.update(venue.id, { display_name: 'Venue A (west)' })
+```
+
+To correct a genuine typo, create the right code, repoint whatever uses it, and
+delete the old one.
+
+### Plan entitlement availabilities
+
+An availability row says when and where one plan entitlement applies: a
+`calendar_id` (null means any date) and `targets`, a set of registered target
+codes (an empty array means anywhere).
+
+```ts
+await ophelio.planEntitlements.createAvailability(planEntitlement.id, {
+  calendar_id: peak.id,
+  targets: ['venue_a'],
+})
+```
+
+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.
+
+Availability rows can be authored today but nothing reads them yet, so they do
+not restrict admission.

package/dist/index.cjs

@@ -126,6 +126,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;
@@ -180,9 +195,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) {
@@ -314,6 +327,125 @@ 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
+* within a rule and rules OR across a calendar, so "weekends in August" is a
+* single rule rather than two.
+*
+* Rules are created and listed through their calendar
+* (`ophelio.calendars.createRule` / `ophelio.calendars.listRules`); this
+* resource addresses an individual rule.
+*/
+var CalendarRulesResource = class extends APIResource {
+	get(id, options) {
+		return this.transport.request({
+			method: "GET",
+			path: `/api/v1/calendar-rules/${encodeURIComponent(id)}`,
+			retryable: true,
+			options
+		});
+	}
+	update(id, params, options) {
+		return this.transport.request({
+			method: "PATCH",
+			path: `/api/v1/calendar-rules/${encodeURIComponent(id)}`,
+			body: params,
+			retryable: false,
+			options
+		});
+	}
+	async delete(id, options) {
+		await this.transport.request({
+			method: "DELETE",
+			path: `/api/v1/calendar-rules/${encodeURIComponent(id)}`,
+			retryable: false,
+			options
+		});
+	}
+};
+//#endregion
+//#region src/resources/calendars.ts
+/**
+* Calendars are named, reusable date vocabularies ("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 {
+	async list(params, options) {
+		const response = await this.transport.request({
+			method: "GET",
+			path: "/api/v1/calendars",
+			query: pageQuery(params),
+			retryable: true,
+			options
+		});
+		return {
+			items: response.calendars,
+			next_page_token: response.next_page_token,
+			total_size: response.total_size
+		};
+	}
+	get(id, options) {
+		return this.transport.request({
+			method: "GET",
+			path: `/api/v1/calendars/${encodeURIComponent(id)}`,
+			retryable: true,
+			options
+		});
+	}
+	create(params, options) {
+		return this.transport.request({
+			method: "POST",
+			path: "/api/v1/calendars",
+			body: params,
+			retryable: false,
+			options
+		});
+	}
+	update(id, params, options) {
+		return this.transport.request({
+			method: "PATCH",
+			path: `/api/v1/calendars/${encodeURIComponent(id)}`,
+			body: params,
+			retryable: false,
+			options
+		});
+	}
+	async delete(id, options) {
+		await this.transport.request({
+			method: "DELETE",
+			path: `/api/v1/calendars/${encodeURIComponent(id)}`,
+			retryable: false,
+			options
+		});
+	}
+	async listRules(id, params, options) {
+		const response = await this.transport.request({
+			method: "GET",
+			path: `/api/v1/calendars/${encodeURIComponent(id)}/rules`,
+			query: pageQuery(params),
+			retryable: true,
+			options
+		});
+		return {
+			items: response.rules,
+			next_page_token: response.next_page_token,
+			total_size: response.total_size
+		};
+	}
+	createRule(id, params, options) {
+		return this.transport.request({
+			method: "POST",
+			path: `/api/v1/calendars/${encodeURIComponent(id)}/rules`,
+			body: params,
+			retryable: false,
+			options
+		});
+	}
+};
+//#endregion
 //#region src/resources/customers.ts
 var CustomersResource = class extends APIResource {
 	/**
@@ -799,6 +931,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) {
@@ -827,6 +998,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
@@ -1061,6 +1255,74 @@ 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.
+*/
+var TargetCodesResource = class extends APIResource {
+	async list(params, options) {
+		const response = await this.transport.request({
+			method: "GET",
+			path: "/api/v1/target-codes",
+			query: pageQuery(params),
+			retryable: true,
+			options
+		});
+		return {
+			items: response.target_codes,
+			next_page_token: response.next_page_token,
+			total_size: response.total_size
+		};
+	}
+	get(id, options) {
+		return this.transport.request({
+			method: "GET",
+			path: `/api/v1/target-codes/${encodeURIComponent(id)}`,
+			retryable: true,
+			options
+		});
+	}
+	/**
+	* `code` is lowercase letters and digits with single underscores between
+	* segments, at least one letter, 2–64 characters. Anything else is refused
+	* with a 400 rather than normalised, so `Venue A` is an error, not
+	* `venue_a`.
+	*/
+	create(params, options) {
+		return this.transport.request({
+			method: "POST",
+			path: "/api/v1/target-codes",
+			body: params,
+			retryable: false,
+			options
+		});
+	}
+	/**
+	* `display_name` and `description` only — `code` is immutable from
+	* creation and sending it is a 400. To correct a typo, create the right
+	* code, repoint whatever uses it, then delete the old one.
+	*/
+	update(id, params, options) {
+		return this.transport.request({
+			method: "PATCH",
+			path: `/api/v1/target-codes/${encodeURIComponent(id)}`,
+			body: params,
+			retryable: false,
+			options
+		});
+	}
+	async delete(id, options) {
+		await this.transport.request({
+			method: "DELETE",
+			path: `/api/v1/target-codes/${encodeURIComponent(id)}`,
+			retryable: false,
+			options
+		});
+	}
+};
+//#endregion
 //#region src/resources/webhook-subscriptions.ts
 var WebhookSubscriptionsResource = class extends APIResource {
 	async list(options) {
@@ -1185,7 +1447,11 @@ var Ophelio = class Ophelio {
 	memberRoles;
 	pricingGroups;
 	salesChannels;
+	targetCodes;
+	calendars;
+	calendarRules;
 	planEntitlements;
+	planEntitlementAvailabilities;
 	planLinks;
 	planPricingGroupMappings;
 	billingOptionSalesChannels;
@@ -1208,7 +1474,11 @@ var Ophelio = class Ophelio {
 		this.memberRoles = new MemberRolesResource(transport);
 		this.pricingGroups = new PricingGroupsResource(transport);
 		this.salesChannels = new SalesChannelsResource(transport);
+		this.targetCodes = new TargetCodesResource(transport);
+		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);