Voila SDK

TypeScript SDK for Voila grocery search, session handling, and cart workflows.

This package wraps the same same-origin JSON endpoints used by the Voila web app. Voila does not publish a third-party customer API, so the SDK treats every live response as an unstable boundary: all I/O payloads are parsed with Effect Schema, failures are typed, and order placement is intentionally out of scope.

Install

pnpm add @firfi/voila-sdk effect

The package is ESM-only and supports Node.js ^22.22.2 || ^24.15.0.

Quick Start

Every operation is an Effect that requires a VoilaTransport. The transport is a service: provide one layer, and every operation in the program uses it.

import { Effect, Layer } from "effect"
import {
  bootstrapGuestSession,
  connectionFailure,
  responseReadFailure,
  searchProducts,
  VoilaTransport
} from "@firfi/voila-sdk"

const responseHeadersFromFetch = (headers: Headers) => {
  const setCookie = headers.getSetCookie()
  const entries = Object.fromEntries(headers.entries())

  return setCookie.length === 0 ? entries : { ...entries, "set-cookie": setCookie }
}

const fetchTransportLayer = Layer.succeed(VoilaTransport, {
  request: (request) =>
    Effect.flatMap(
      Effect.tryPromise({
        catch: connectionFailure,
        try: () =>
          fetch(request.url, {
            ...(request.body === undefined ? {} : { body: request.body }),
            headers: request.headers,
            method: request.method,
            redirect: "manual"
          })
      }),
      (response) =>
        Effect.map(
          Effect.tryPromise({ catch: responseReadFailure, try: () => response.text() }),
          (body) => ({ body, headers: responseHeadersFromFetch(response.headers), status: response.status })
        )
    )
})

const program = Effect.gen(function*() {
  const bootstrap = yield* bootstrapGuestSession()
  const search = yield* searchProducts(bootstrap.session, { pageSize: 12, query: "milk" })

  return search.value.products.map((product) => product.name)
})

console.log(await Effect.runPromise(Effect.provide(program, fetchTransportLayer)))

Failures stay in the typed error channel: Effect.result turns them into a Result where a caller would rather branch than short-circuit.

What It Supports

• Guest session bootstrap from Voila homepage state.
• Product search and category product reads.
• Cart reads, item add/remove, and server-returned cart totals.
• Authenticated session health checks and authenticated cart reads.
• Keepalive classification helpers and schema-owned KeepaliveOutcome, KeepaliveStopReason, KeepaliveConfig, and timing contracts.
• Delivery destination/context reads and guarded delivery context changes.
• Slot listing and guarded slot reservation input helpers.
• Checkout summary/readiness review.
• Completed order history reads with cursor pagination.
• Completed order detail reads with item groups, quantities, prices, and substitution/missing/return status.
• Completed-order item aggregation for questions like "what did I order last month?"
• Session snapshot save/load helpers.

The SDK does not place orders. Checkout APIs stop at review/readiness so a human can confirm in Voila.

Authenticated Sessions

The SDK never accepts or stores a password. Use the local capture helper to log in interactively and save a session snapshot:

pnpm auth:capture

The command opens Chromium, waits for Voila session material, and writes:

local-session-snapshots/voila-auth-session.json

That file is sensitive and ignored by git. Use it with loadSdkSessionSnapshot and checkSessionHealth before authenticated reads or cart mutations. See docs/browser-login.md and docs/auth-readonly-smoke.md.

The SDK exports KeepaliveOutcomeSchema, KeepaliveStopReasonSchema, and KeepaliveConfigSchema as runtime contracts. KeepaliveIntervalSecondsSchema accepts only canonical whole-second strings from 3600 through the safe millisecond-conversion limit. KeepaliveHealthyIntervalMsSchema, KeepaliveRetryDelayMsSchema, and KeepaliveMaxRetryDelayMsSchema are distinct positive safe-integer brands; use keepaliveIntervalMsFromSeconds after parsing an interval. KeepaliveExpiryPolicySchema distinguishes background "continue" from foreground "stop" behavior. classifyHealthStatus and describeKeepaliveOutcome are pure; the Effect-native loop and foreground signal handling live in @firfi/voila-mcp.

Browser login timeout values are likewise constrained by the branded BrowserLoginTimeoutMsSchema before they reach a browser adapter.

Public API

Import only from the package entrypoint:

import { addCartItems, getCart, getCompletedOrderItems, getCompletedOrders, getOrderDetails, searchProducts } from "@firfi/voila-sdk"

Deep imports are unsupported. See docs/public-api.md for the full public surface and docs/usage-examples.md for end-to-end examples.

Development

This repository follows the same quality harness as ../hulymcp: Effect-first TypeScript, Effect Schema at I/O boundaries, type-aware Oxlint and Effect diagnostics, Oxc formatting through dprint, property tests, complexity and package-boundary checks, coverage gates, duplication checks, circular dependency checks, and Husky pre-commit hooks.

pnpm install
pnpm check-all
pnpm package:audit

pnpm check-all runs named stages with timeouts and a bounded output budget: build, package boundaries, TypeScript and Effect diagnostics, circular dependencies, cyclomatic complexity, registry metadata, lint/format/duplication, fixture audit, and independently verified coverage-gated tests.

pnpm package:audit builds the SDK and verifies the local npm dry-run package contents. See docs/package-audit.md.

Live Smoke Tests

Default checks never hit Voila. Live smoke tests are opt-in:

VOILA_LIVE_SMOKE=1 pnpm smoke:catalog-search
VOILA_LIVE_SMOKE=1 pnpm smoke:cart
VOILA_AUTH_SMOKE=1 VOILA_AUTH_SESSION_PATH=/absolute/path/to/sdk-session.json pnpm smoke:auth-readonly
VOILA_DRIFT_AUDIT=1 pnpm drift:audit

The catalog smoke bootstraps a guest session and searches milk.

The cart smoke uses a guest session, adds one available product, reads the server cart, removes that product, and verifies cleanup.

The authenticated read-only smoke loads a caller-provided authenticated SDK session snapshot, checks session health, searches milk, and reads the active cart.

The endpoint drift audit bootstraps a guest session, searches milk, and reads the guest cart to detect likely Voila response-schema drift.

Edge Blocking Diagnostics

Voila may change its unofficial web endpoints or security rules without notice. Blocked requests return a safe VoilaRequestBlocked error without response bodies or session secrets. See request identity and blocking for details.

Release

Use the release gate before publishing:

pnpm release:check
npm publish

The package tarball intentionally contains only package.json, README.md, LICENSE, and dist/src/**. See docs/release.md.

MCP And CLI

The workspace also publishes @firfi/voila-mcp and @firfi/voila-cli. Both use this SDK for Voila endpoint behavior; MCP owns the shared operation registry and the CLI reuses it. See docs/mcp-readiness.md.

Safety

• Do not store Voila passwords.
• Treat session snapshots, browser profiles, cookies, and CSRF tokens as secrets.
• Do not log cookies, CSRF tokens, payment data, addresses, or account identifiers.
• Do not place an order without explicit caller confirmation from the latest checkout summary.
• Use docs/safety-review-checklist.md before merging changes that touch live network behavior, auth, cart mutation, slots, checkout review, fixtures, or diagnostics.