npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

acai-demo-sdk

v0.7.2

Published

Shared Try Demo feature package — session-end redirect claim, expiry polling, persona switching against auth-sso-server's /demo/* endpoints, and the DemoModeBar UI itself. Each consuming app supplies its own cookie adapter and post-switch navigation inste

Readme

açai demo SDK

Shared Try Demo package for açai apps: session-end redirect claim, expiry polling, persona switching against auth-sso-server's /demo/* endpoints, and the DemoModeBar UI.

Repository: getacaii/acai-demo-sdk. Default branch: main.

What it does

  • Provides the React pieces and helpers every frontend needs to run a Try Demo session. Each consuming app supplies its own cookie adapter and post-switch navigation.
  • Carries the backend clone and teardown contract types, type-only and safe to import from a NestJS backend.
  • Sits between the app frontends and auth-sso-server (the /demo/* endpoints); it has no server of its own.

Tech stack

  • TypeScript, React (peer dependency ^18 || ^19), acai-ui-library (peer dependency)
  • Tests: Vitest
  • Published to the public npm registry as acai-demo-sdk by the Publish workflow on v* tags

Getting started

Prerequisites: Node.js 22 and npm.

npm ci                            # Install dependencies
npm run build                     # Compile with tsc
npm run lint                      # Lint
npm run test                      # Unit tests

No environment variables are read by the package itself; consuming apps pass the SSO URL and cookie settings in. acai-demo-sdk/env provides assertProductionUrl() for use in next.config.

Entry points

| Import | Contents | |---|---| | acai-demo-sdk | Hooks, DemoModeBar and shell components | | acai-demo-sdk/client | Client for the /demo/* endpoints | | acai-demo-sdk/middleware-token | pickAccessToken() for Next.js middleware | | acai-demo-sdk/env | Environment guards such as assertProductionUrl() | | acai-demo-sdk/contracts | Clone and teardown contract types (type-only) | | acai-demo-sdk/fixture | The one fictional template company (no React) | | acai-demo-sdk/server | Kind client, template-ready rule, template lock key (Node only) | | acai-demo-sdk/testing | Test helpers for consumers |

Project structure

src/        client, hooks, components, contracts, fixture and server helpers
test/       unit tests
.github/    CI and publish workflows

Deployment

This is a library, not a service. A v* tag triggers .github/workflows/publish.yml, which publishes to npm. Apps pick up a new version by bumping the dependency; their own deploys follow the reusable workflows in getacaii/acai-ai-platform (docs/CI-CD-STANDARD.md).

Contributing

  • Work starts from a task issue in getacaii/acai-ai-platform; the PR rules are in docs/TASK-LIFECYCLE.md there.
  • Open the PR against the default branch (main here) with a Conventional Commits title.

Release notes

Removed in 0.7.0: session.getEmployeePortalLink (from useDemoSession and the UseDemoSessionResult type). auth-sso-server no longer serves GET /demo/employee-portal-link, so the method could only return null. Nothing in the estate calls it. Delete any use; there is no replacement.

0.7.0

  • Product analytics for signed-in users: createProductAnalytics (root entry and the React-free acai-demo-sdk/client). It reuses the Try Demo tracker's batching and cleaning and posts to auth-sso-server POST /api/v1/analytics/events with the user's access token (acai-ai-platform#1260, see docs/platform/product-analytics.md). See "Product analytics" below.
  • The Try Demo tracker now sends through a shared batcher (telemetry-batcher.ts). Its behaviour is unchanged: same URL, body, limits and stop rules.
  • SDK_VERSION ('acai-demo-sdk/server') is now 0.7.0. An app that adopts this release will report its template as stale and rebuild it on the next "Provision now".

Product analytics

import { createProductAnalytics } from 'acai-demo-sdk/client';

const analytics = createProductAnalytics({
  endpoint: process.env.NEXT_PUBLIC_SSO_URL!,      // or the full .../api/v1/analytics/events URL
  getAccessToken: () => getAccessTokenFromCookie(), // may also return a Promise
  appId: 'hrms',                                    // the registry app id
  consent: userConsented,                           // nothing is sent until this is true
  optOut: profile.analyticsOptOut,                  // the per-user opt-out, if known at start-up
  routeTemplate: (path) => path,                    // optional; default: uuid and numeric segments -> :id
});
const unwire = analytics.start(); // clicks, visibility, pagehide, a 1 s route poll; call unwire() on unmount

analytics.trackAction('invoice.create');
analytics.trackFunnelStep('onboarding', 'invite-sent');
analytics.setOptOut(true); // stops sending and drops what is queued

What it records and what it never records:

  • Routes: only the template. The query string and fragment are cut before your mapper sees the path, and the result is cleaned again (cleanRoutePath), so /people/[email protected]/edit?tab=salary is sent as /people/:id/edit.
  • Clicks: the element's ARIA role (explicit or implied by the tag) and its data-analytics-id, plus the click position in percent and a viewport bucket. Never text content, never input values, never aria-label (labels often hold names). Add data-analytics-id to the controls you want named in the heatmaps. Put data-analytics-mask on an element or a whole section to skip clicks in it entirely.
  • Actions and funnel steps: short identifiers only (invoice.create); names with spaces, @ or ids are dropped.
  • Consent: off until consent: true (or setConsent(true)). Global Privacy Control or Do Not Track = nothing is sent at all. setOptOut(true) or setConsent(false) stops sending and drops the queue. The server checks the tenant switch and the user's opt-out again and answers 204 without storing anything.
  • No user id, tenant id, email or role is ever in the payload: the server takes the tenant and user from the token.
  • At most 50 events and about 14 KB per call (the server's limit is 16 KB), every 10 s, keepalive so the last batch survives a page close. A 401 is retried on the next batch (tokens refresh); other 4xx stop the tracker.

0.6.4

  • DemoShell's extraActions can be a function of the session. Pass extraActions={(session) => ...} to build an app button that uses the session, for example pay's "View as Employee" (session.getEmployeePortalLink(...)). The function is called only while the bar shows. A plain node still works as before.
  • SDK_VERSION ('acai-demo-sdk/server') is now 0.6.4. An app that adopts this release will report its template as stale and rebuild it on the next "Provision now".

0.6.3

  • DemoEndedScreen takes a logo (any React node, shown above the title), like DemoShell already does for the "your demo is ending" screen. Without it an app moving from its own demo-ended page to the shared one would lose its logo. Omit it for no logo.
  • SDK_VERSION ('acai-demo-sdk/server') is now 0.6.3. An app that adopts this release will report its template as stale and rebuild it on the next "Provision now".

0.6.2

  • Types for commonjs (node10) projects. acai-demo-sdk/testing and acai-demo-sdk/client had no typesVersions entry, so a project compiled with module: commonjs and no moduleResolution (node10 ignores exports) failed with TS2307 on those two imports. hrms-backend worked around it with a tsconfig paths entry and itam-backend with a type shim: both can be removed once they are on 0.6.2. A test now fails if an exported subpath has no typesVersions entry.
  • SDK_VERSION ('acai-demo-sdk/server') is now 0.6.2. An app that adopts this release will report its template as stale and rebuild it on the next "Provision now".

0.6.1

Four helpers for backends and frontends. Nothing existing changes.

  • Contract check (acai-demo-sdk/testing): expectDemoContract(call) in an app's own spec sends the bodies auth-sso-server really sends (demoContractCases()) through the app's real routes and fails with one list of every case answered outside DEMO_ROUTE_STATUS, naming a 400/422 as "rejected the body". A DTO that only implements the contract type does not catch a field the app left out; this does (projects-backend answered 400 property apps should not exist on provision-template).
  • Last look (acai-demo-sdk/server): createLastLook(getKind, tenantId, expected = 'demo') returns a function to call as the last step inside the transaction. It asks auth-sso-server again and throws DemoTenantGoneError unless the tenant still has the expected kind, so a demo torn down while the work ran rolls back instead of committing. An unreachable auth-sso-server stays DemoKindUnavailableError (retryable), never "gone".
  • Teardown helper (acai-demo-sdk/server): runTeardown({ collectBlobKeys, deleteRows, deleteBlob, purgeQueues }) runs the fixed order (collect file keys, delete rows, delete files, purge queues) and returns a count per step. A failure before the rows are deleted throws as is and leaves files and queues alone. After that, a failing file or purge does not stop the rest and DemoTeardownIncompleteError carries the report. Once the rows are gone a failed file key cannot be found again on a retry: log the keys in the report.
  • DemoShell and DemoEndedScreen (acai-demo-sdk): one component for the status poll, the bar, the role switch (with an inline error and Retry), the ending screen and the layout offset, instead of a copied banner per app, and a demo-ended page. The hook callbacks are kept stable inside, so a parent's inline arrow cannot re-fire the poll into a 429. topOffset={false} for a layout in normal flow. DemoEndedScreen takes reason (ENDED, EXPIRED, FAILED) as a prop: auth-sso-server stores endReason but does not return it yet.
  • SDK_VERSION ('acai-demo-sdk/server') is now 0.6.1. An app that adopts this release will report its template as stale and rebuild it on the next "Provision now".

0.6.0

  • Status codes (acai-demo-sdk/contracts): DEMO_STATUS (OK 200, ACCEPTED 202), DEMO_ROUTE_STATUS and isDemoRouteStatus(route, status). auth-sso-server accepts 200 or 202 from clone and provision-template, and only 200 from teardown and template-status. Never 201, which is what Nest answers on a POST that forgot @HttpCode. Use @HttpCode(DEMO_STATUS.OK) and assert the route's code in the app's own spec with isDemoRouteStatus.
  • Usage telemetry for the Try Demo heatmap, inside useDemoSession. On by default; pass telemetry: false to turn it off. It records which pages a visitor opens (the route with ids replaced by :id, never the query string or the fragment), where they click (position as a percent of the viewport, a viewport bucket and an element key from data-demo-feature, else data-testid, else tag:role), how long the tab is in front (visible and active in the last 30 s) and role switches. It never reads text or input values, and never sends the persona's user id. It sends the role's display name. Batches go to POST /demo/events every 10 s (or 20 events, or 12 KB) with the demo JWT and keepalive, and the last batch goes on pagehide.
    • Add data-demo-feature="leave/approve" to a key control to name the feature its clicks belong to.
    • Global Privacy Control or Do Not Track: only app, role and time are sent (no routes, no clicks).
    • Nothing is sent from the demo entry (/app/demo-entry) and ended pages.
    • Best effort, never noise: it stops after any 4xx except 408 and 429 (404 = an older auth-sso-server without the route or a demo that is off, 401/403 = a bad token, 405, 413...), and after 3 failed batches in a row (5xx, 429, a network or CORS error). It never throws into the page. Event times use the server clock offset the hook already tracks, because the server drops an event more than a minute away from its own clock.
    • acai-demo-sdk/client also exports the React-free core (createDemoTelemetry, cleanRoutePath, ...).
    • Tests in an app that count fetch calls will now also see the /demo/events request (on a flush, or when the hook unmounts): filter it out, or pass telemetry: false in that test.
    • Limits, on purpose: the element key and the route are cleaned (characters, and ids/tokens/emails become :id), but a data-testid or data-demo-feature that itself contains a name (row-jane-doe) or a route word that is a plain name (/employees/alice) is still sent as written. Keep names out of test ids and routes. In React StrictMode (development only) the first page view can be sent twice.
    • The notice shown to visitors (what is recorded and how to opt out) is NOT part of this release; its wording needs a legal check.
  • SDK_VERSION ('acai-demo-sdk/server') is now 0.6.0. An app that adopts this release will report its template as stale and rebuild it on the next "Provision now" (that is what the version is for).

0.3.0 (breaking for 0.x consumers)

  • The demo JWT now lives in its own cookie, demo_accessToken (DEMO_ACCESS_TOKEN_COOKIE), never the real-login accessToken. Write/clear it only through this package (writeDemoCookie, clearDemoState, endDemoSessionRedirect); read the token an API client should send with getActiveAccessToken() (demo first, then real). Proxies/middleware use pickAccessToken() from acai-demo-sdk/middleware-token.
  • POST /demo/start returns a pollToken; every GET /demo/status/:id sends it as x-demo-poll-token. It lives in sessionStorage only and reaches /demo-entry in the URL fragment (consumeDemoEntryFragment()).
  • useDemoSession keeps callbacks in refs, applies a server-time offset, re-confirms expiry against /status (the server is the authority), backs off on 429/5xx (reconnecting), and exposes isSwitching / reconnecting / error. DemoModeBar takes switching / reconnecting.
  • acai-demo-sdk/env: assertProductionUrl() for next.config so a production build never ships a localhost SSO URL.

License and ownership

© Humancloud Technologies Private Limited. All rights reserved.