npm - @peektravel/app-utilities - Versions diffs - 0.1.1 → 0.1.3 - Mend

@peektravel/app-utilities 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/README.md CHANGED Viewed

@@ -7,26 +7,15 @@ high-level `PeekAccessService` and the plain data shapes it returns.
 ## Install
-This package is published to **GitHub Packages** (a private registry), not the
-public npm registry. Point the `@peek-travel` scope at GitHub Packages once per
-consuming project by adding an `.npmrc` next to its `package.json`:
-```ini
-@peek-travel:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${NPM_TOKEN}
-```
-Then install (and later update) it like any other dependency:
+This package is published to the **public npm registry**. Install (and later
+update) it like any other dependency — no registry config or auth token needed:
 ```bash
 npm install @peektravel/app-utilities
 npm update  @peektravel/app-utilities
 ```
-`NPM_TOKEN` must be a GitHub token with the `read:packages` scope. Locally that's
-a personal access token in your environment; in cloud builds (Firebase
-Functions / Google Cloud Build, CI) set it as a build secret/env var. See
-[Releasing](#releasing-github-packages) for how new versions are published.
+See [Releasing](#releasing) for how new versions are published.
 ## Usage
@@ -207,13 +196,90 @@ both `import` and `require` consumers (including the Node 22 / CommonJS Firebase
 Functions runtime) resolve correctly. Its only runtime dependency is
 `jsonwebtoken`.
-## Releasing (GitHub Packages)
+## UI components (`/ui`)
+The package also ships framework-agnostic **Web Components** ported from the Peek
+Odyssey design system, under a separate browser-only subpath so the server
+library stays DOM-free. They work in any HTML page — no framework required.
+```ts
+// Registers every <ody-*> custom element as a side effect.
+import '@peektravel/app-utilities/ui';
+import '@peektravel/app-utilities/ui/tokens.css';
+import '@peektravel/app-utilities/ui/odyssey.css';
+```
+```html
+<ody-button variant="primary" left-icon="plus">New booking</ody-button>
+<ody-tag color="success" icon="check">Confirmed</ody-tag>
+<ody-alert variant="warning" heading="Heads up">This can't be undone.</ody-alert>
+<ody-input label="Guest name" placeholder="Jane Doe"></ody-input>
+```
+Coverage spans display (button, tag, alert, card, status-dot, message, icon,
+loading-spinner/bar, divider), layout (empty-state, breadcrumb, stat-summary,
+inline-list, list-item, product-indicator, toggle-button, section, two-column,
+collapsible-section), form inputs (input, inline/search/money/percentage input,
+checkbox, radio-button-group, checkbox-group), interactive (accordion,
+collapsible, tabs, copy-button, check-in-status, option, split-button,
+table-header), overlays (modal, popover, tooltip, panel, toast), and data &
+selection (dropdown-single, dropdown-multi, datepicker, table — all vanilla and
+dependency-free, following WAI-ARIA combobox/listbox/grid patterns).
+Interactive components reflect state and emit `CustomEvent`s; grouped components
+(tabs, radio/checkbox groups, toggle group) take a JSON `options`/`tabs`
+attribute. Exported classes/types and helpers (`iconSvg`, `registerIcon`,
+`portal`, `position`, `toast`) are available from `@peektravel/app-utilities/ui`
+for subclassing or typing.
+**Try the gallery:** `npm run sample` builds the package and serves
+`examples/ui-gallery.html`, which shows every component with its variants.
+### Localization
+Content you pass in (labels, headings, options, cell data) is already yours to
+localize. The components' **own** built-in strings (aria-labels like "Close" /
+"Clear", the date picker's "Select date" and month-nav labels, the dropdown
+"Search" / "No options", the check-in-status labels) are translatable two ways:
+```ts
+import { registerTranslation } from '@peektravel/app-utilities/ui';
+registerTranslation('es', {
+  close: 'Cerrar', clear: 'Borrar', search: 'Buscar',
+  checkInReturned: 'Devuelto', /* … */
+});
+```
+Each component resolves its language from the nearest `lang` attribute
+(`<html lang="es">` localizes everything; a subtree `lang` overrides it), and
+re-renders automatically when the language or a registered bundle changes.
+English is the built-in default. For a one-off, a per-instance attribute wins:
+`<ody-panel close-label="Cerrar">`, `<ody-datepicker next-month-label="…">`,
+`<ody-check-in-status label="…">`.
+The **date picker** displays dates with `Intl.DateTimeFormat` for the resolved
+`lang` — a readable, localized label (e.g. "Jun 15, 2026" / "15 jun 2026")
+rather than the raw ISO string. Its `value` attribute and `change` payload stay
+machine-readable ISO `yyyy-mm-dd` (range as `start/end`). Tune the displayed
+form with `display-format` (`short` | `medium` | `long` | `full`) or take full
+control with the `formatDate` property. Weekday/month names and day labels in
+the calendar are likewise `Intl`-localized, so they aren't in the term catalog.
+> A few Odyssey components remain unported: `nested-multi-select`,
+> `location-autocomplete` (Google Maps API), `filter-menu` / `filter-menu-single`,
+> `accordion-checkbox`, and `datepicker-with-presets`. The dropdowns, the single
+> date picker, and the data table were rebuilt here as lightweight,
+> dependency-free vanilla components rather than ported from their
+> third-party-coupled Ember originals.
+## Releasing
 Releases are automated. Pushing a `v*.*.*` git tag triggers
 `.github/workflows/publish.yml`, which typechecks, lints, runs the test suite
-(95% coverage gate), then publishes to GitHub Packages. `npm publish` runs
-`prepublishOnly` first, so the build plus `publint` + `attw` checks gate every
-release.
+(95% coverage gate), then publishes to the public npm registry. `npm publish`
+runs `prepublishOnly` first, so the build plus `publint` + `attw` checks gate
+every release.
 To cut a release:
@@ -223,13 +289,14 @@ git push --follow-tags     # pushes the commit + tag; the workflow publishes
 ```
 The workflow asserts the tag matches the `package.json` version, so the two
-never drift. The repo's built-in `GITHUB_TOKEN` (with `packages: write`) handles
-publish auth — no personal token needed in CI. Consumers then pick the new
-version up with a normal `npm update` (see [Install](#install)).
+never drift. Publish auth uses an `NPM_TOKEN` repository secret (an npm
+automation token with publish rights to the `@peektravel` scope), exposed to
+`npm publish` as `NODE_AUTH_TOKEN`. Consumers then pick the new version up with
+a normal `npm update` (see [Install](#install)).
-> One-time setup: the package scope `@peek-travel` must match the GitHub org
-> that owns the package, and the repo needs the GitHub Actions permission to
-> write packages (granted by the `packages: write` permission in the workflow).
+> One-time setup: add an `NPM_TOKEN` secret to the repository (Settings →
+> Secrets and variables → Actions). Generate it on npmjs.com as an **Automation**
+> token so it bypasses 2FA in CI.
 ## Development
@@ -249,13 +316,15 @@ npm run lint       # eslint (flat config)
 and [`@arethetypeswrong/cli`](https://github.com/arethetypeswrong/arethetypeswrong.github.io)
 to verify the `exports` map and type resolution are correct for both module
 systems. The publish workflow runs these automatically — see
-[Releasing](#releasing-github-packages).
+[Releasing](#releasing).
 ## Project layout
 ```
-src/                       source (public API barrel: src/index.ts)
-test/                      vitest unit tests
+src/                       server library source (public API barrel: src/index.ts)
+src/ui/                    Web Components + Odyssey CSS (barrel: src/ui/index.ts)
+test/                      vitest unit tests (test/ui/* run under happy-dom)
+examples/ui-gallery.html   component gallery (npm run sample)
 dist/                      build output (generated, git-ignored)
 docs/internal/             maintainer docs (ARCHITECTURE.md — not shipped)
 llms.txt                   AI-agent quickstart (shipped in the package)

package/dist/index.cjs CHANGED Viewed

@@ -2151,6 +2151,132 @@ var ResourcePoolService = class {
   }
 };
+// src/internal/reviews/review-converter.ts
+var ISO_DATE_LENGTH = 10;
+function toDateOnly(isoDateTime) {
+  return isoDateTime.slice(0, ISO_DATE_LENGTH);
+}
+function fromReviewNode(node) {
+  const guides = (node.guides ?? []).map((guide) => ({
+    id: guide.id,
+    name: guide.name
+  }));
+  return {
+    id: node.id,
+    productId: node.activity?.id ?? "",
+    productName: node.activity?.name ?? "",
+    guides,
+    customerName: node.name ?? null,
+    customerEmail: node.email ?? null,
+    activityDate: toDateOnly(node.purchasedFor),
+    reviewDate: toDateOnly(node.reviewedAt),
+    rating: node.rating,
+    comment: node.comment ?? null
+  };
+}
+// src/internal/reviews/review-cursor.ts
+function encodeCursor(offset, pageSize) {
+  const start = Math.max(0, offset - pageSize + 1);
+  return Buffer.from(`range:${start}..${offset},${offset}`).toString("base64");
+}
+// src/internal/reviews/review-queries.ts
+var REVIEWS_QUERY = `
+  query Reviews($first: Int, $filter: ReviewFilter, $after: String) {
+    reviews(first: $first, filter: $filter, after: $after) {
+      edges {
+        node {
+          activity {
+            id
+            name
+          }
+          guides {
+            id
+            name
+          }
+          id
+          name
+          email
+          rating
+          comment
+          reviewedAt
+          purchasedFor
+        }
+        cursor
+      }
+    }
+  }
+`;
+function buildReviewsVariables(params) {
+  return {
+    first: params.first,
+    filter: { activityIds: [params.activityId] },
+    after: params.after
+  };
+}
+// src/internal/reviews/review-service.ts
+var DEFAULT_REVIEW_COUNT = 50;
+var MIN_REVIEW_COUNT = 1;
+var MAX_REVIEW_COUNT = 50;
+var ERROR_PRODUCT_ID_REQUIRED = "productId is required";
+var ERROR_INVALID_REVIEW_COUNT = `reviewCount must be an integer between ${MIN_REVIEW_COUNT} and ${MAX_REVIEW_COUNT}`;
+var ERROR_INVALID_REVIEW_OFFSET = "reviewOffset must be a non-negative integer";
+var ReviewService = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Returns up to `reviewCount` reviews for an activity in **descending order
+   * by review date (newest first)**, skipping the `reviewOffset` newest reviews
+   * before collecting.
+   *
+   * The gateway cursor resumes *after* a given absolute offset, so to skip the
+   * first `reviewOffset` reviews the request is anchored on the review just
+   * before the window. A `reviewOffset` of 0 needs no cursor and is sent
+   * without one.
+   *
+   * @param productId - The activity (product) id to fetch reviews for.
+   * @param reviewCount - How many reviews to return (1–50). Default: 50.
+   * @param reviewOffset - How many of the newest reviews to skip first
+   *   (0-based). Default: 0 (start at the newest review).
+   *
+   * @throws {Error} when `productId` is empty, `reviewCount` is not an integer
+   * in 1–50, or `reviewOffset` is not a non-negative integer.
+   *
+   * @example
+   * ```ts
+   * const reviews = await peek
+   *   .getReviewService()
+   *   .getReviews("87cdf37f-1872-42cb-b0bd-518312624fc1", 25, 50);
+   * ```
+   */
+  async getReviews(productId, reviewCount = DEFAULT_REVIEW_COUNT, reviewOffset = 0) {
+    this.validate(productId, reviewCount, reviewOffset);
+    const after = reviewOffset > 0 ? encodeCursor(reviewOffset - 1, reviewCount) : null;
+    const body = await this.client.request(
+      SALES_ENDPOINT,
+      REVIEWS_QUERY,
+      buildReviewsVariables({ activityId: productId, first: reviewCount, after })
+    );
+    const edges = body.data?.reviews?.edges ?? [];
+    return edges.map((edge) => fromReviewNode(edge.node));
+  }
+  validate(productId, reviewCount, reviewOffset) {
+    if (!productId) {
+      throw new Error(ERROR_PRODUCT_ID_REQUIRED);
+    }
+    if (!Number.isInteger(reviewCount) || reviewCount < MIN_REVIEW_COUNT || reviewCount > MAX_REVIEW_COUNT) {
+      throw new Error(ERROR_INVALID_REVIEW_COUNT);
+    }
+    if (!Number.isInteger(reviewOffset) || reviewOffset < 0) {
+      throw new Error(ERROR_INVALID_REVIEW_OFFSET);
+    }
+  }
+};
 // src/internal/timeslots/timeslot-converter.ts
 function fromTimeslotNodes(nodes, productId) {
   if (!Array.isArray(nodes) || nodes.length === 0) {
@@ -2798,6 +2924,7 @@ var PeekAccessService = class {
   availabilityService;
   membershipService;
   bookingService;
+  reviewService;
   constructor(config) {
     requireNonEmpty(config.installId, "installId");
     requireNonEmpty(config.jwtSecret, "jwtSecret");
@@ -2934,6 +3061,16 @@ var PeekAccessService = class {
     }
     return this.bookingService;
   }
+  /**
+   * Returns the {@link ReviewService} for this install, bound to the shared
+   * authenticated transport. The instance is created lazily and reused.
+   */
+  getReviewService() {
+    if (!this.reviewService) {
+      this.reviewService = new ReviewService(this.client);
+    }
+    return this.reviewService;
+  }
 };
 function requireNonEmpty(value, name) {
   if (!value) {
@@ -2955,6 +3092,7 @@ exports.PromoCodeService = PromoCodeService;
 exports.RateLimitError = RateLimitError;
 exports.ResellerService = ResellerService;
 exports.ResourcePoolService = ResourcePoolService;
+exports.ReviewService = ReviewService;
 exports.TimeslotService = TimeslotService;
 exports.noopLogger = noopLogger;
 //# sourceMappingURL=index.cjs.map