@pulseindex/sdk 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+## 2.0.0
+
+### Breaking: three methods removed
+
+`createSnapshot()`, `getRecoveryState()` and `setCdcOffset()` are gone, along
+with the `RecoveryState`, `CreateSnapshotResponse` and `SetCdcOffsetResponse`
+types and the RPCs behind them in the bundled proto.
+
+No key issued from the dashboard could call them — every attempt returned a
+permission error — so nothing that worked before stops working. If you were
+calling them and getting errors, that is the code to delete.
+
+**Checking readiness:** use `health()`, or `servingStatus()` when you need to
+tell "not answering" apart from "not reachable". Both work with any key.
+
+### The bundled proto now describes only the client's contract
+
+Four RPCs: `IndexEntity`, `BatchIndexEntities`, `DeleteEntity`, `Search`. The
+drift check that keeps this file honest was changed to match: it verifies every
+declaration here exists identically in the service, and no longer requires the
+two to be identical.
+
+## 1.1.4
+
+Documentation only.
+
+The README documented three methods no ordinary API key can call, and explained
+that they need an elevated one. That is operator surface, and it was dead
+reading for anyone the README is written for. It also named the server-side
+environment variable that holds API keys, which is not the client's business.
+
+`health()` is now described by what it tells you rather than by the protocol
+underneath it, and the production example uses a real endpoint.
+
+The methods still exist on the client; they are simply no longer presented as
+part of the product.
+
+## 1.1.3
+
+No code change. The package now ships only what is needed to use it.
+
+- Source maps are no longer published. They embedded the complete TypeScript
+  source of every bundled file and were 59% of the tarball. The shipped
+  JavaScript is unminified, so stack traces still land somewhere readable.
+- Build, release and proto-sync notes moved out of the README; they described
+  how the SDK is maintained, not how to call it.
+- The RPC table lists the calls a normal API key can make. The three
+  operator-only ones are noted rather than tabulated.
+
+318 KB to 130 KB.
+
+## 1.1.2
+
+Documentation only; the code is identical to 1.1.0.
+
+The vendored `engine.proto` still described how the service works rather than
+how to call it. Found by reading the file rather than searching it for known
+words — which is the only method that finds what you did not already know to
+look for.
+
+## 1.1.1
+
+Documentation only; the code is identical to 1.1.0.
+
+1.1.0 shipped internal maintainer comments in its type declarations and source
+maps — `tsup` emits JSDoc into `.d.ts` and embeds the whole TypeScript source
+into `.map`, and both are in the tarball. 1.1.0 has been unpublished.
+
+## 1.1.0
+
+### `health()` no longer reports false for every key
+
+`health()` used an operator-only call that customer API keys are not permitted to
+make. The permission error was caught and turned into `false`, so the method
+reported an unusable service no matter how healthy it actually was.
+
+It now uses the standard `grpc.health.v1.Health` protocol, which requires no
+particular scope. The signature is unchanged. If you were working around this by
+ignoring `health()`, you can stop.
+
+### Added
+
+- `client.servingStatus(service?)` — the raw serving status, for telling
+  "reachable but not serving" apart from "no answer at all". Defaults to `''`,
+  the overall-server name from the health spec.
+- `SERVING_STATUS` — the status constants, exported from the package root.
+- `healthProtoPath` on the client config, for the rare case of overriding the
+  bundled `health.proto`.
+
+`proto/health.proto` now ships with the package. It is the standard health
+protocol, vendored rather than pulled in as a dependency.
+
+### Compatibility
+
+Against a service deployed before this release, the health protocol answers but
+always reports `SERVING`. `health()` is then equivalent to a reachability check.
+
+## 1.0.0
+
+Initial release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PulseIndex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,326 @@
+# PulseIndex JavaScript / TypeScript SDK
+
+Official Node.js & TypeScript client for **PulseIndex** — hosted search and filtering for large entity sets.
+
+You send attributes to index and queries to run; PulseIndex returns matching entity IDs, which you hydrate from your own database. Your records stay in your primary store — the service holds only what it needs to answer queries.
+
+[![npm version](https://img.shields.io/npm/v/@pulseindex/sdk.svg)](https://www.npmjs.com/package/@pulseindex/sdk)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](#installation)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+## Key features
+
+- Dual ESM / CommonJS build for Node.js 18+
+- Typed fluent `QueryBuilder` matching `pulseindex-php`
+- Zero-dependency GeoHash radius coverage (`geo:{precision}:{hash}`)
+- Connection pooling, deadlines, and `x-api-key` / `Authorization: Bearer` metadata
+- Attribute flattening so plain objects index without a schema (categories, flags, geo tags, price)
+
+## Installation
+
+```bash
+npm install @pulseindex/sdk
+```
+
+```bash
+pnpm add @pulseindex/sdk
+```
+
+ESM:
+
+```ts
+import PulseIndex, { GeoHash } from '@pulseindex/sdk';
+```
+
+CommonJS:
+
+```js
+const { PulseIndex, GeoHash } = require('@pulseindex/sdk');
+```
+
+Requires Node.js 18 or later. The engine gRPC endpoint defaults to `localhost:50051`.
+
+## Quickstart
+
+```ts
+import PulseIndex, { GeoHash } from '@pulseindex/sdk';
+
+const client = new PulseIndex({
+  endpoint: 'localhost:50051',
+  apiKey: process.env.PULSEINDEX_API_KEY,
+  tenantId: 'acme_corp',
+});
+
+await client.index('1001', {
+  categories: ['features:swimming_pool'],
+  category: 'villa',
+  status: 'listed',
+  price: 250000,
+  lat: 41.0082,
+  lng: 28.9784,
+});
+
+const result = await client.search(
+  PulseIndex.query()
+    .tenant('acme_corp')
+    .must('features:swimming_pool')
+    .should(['category:villa', 'category:apartment'])
+    .mustNot('status:sold')
+    .range('price', 100000, 500000)
+    .withinRadius({ lat: 41.0082, lng: 28.9784, radiusKm: 5 })
+    .limit(50),
+);
+
+const ids = result.matchedEntityIds;
+await client.close();
+```
+
+Index-time geo tags should use the same dual precision as radius queries:
+
+```ts
+const tags = GeoHash.encodeMultiTags(41.0082, 28.9784);
+// ['geo:5:sxk97', 'geo:6:sxk976'] (example)
+```
+
+## gRPC configuration
+
+Create a client against any PulseIndex Engine endpoint. Production customer gRPC should set `ssl: true` (or `PULSEINDEX_SSL=true`). The default is plaintext for local development.
+
+```ts
+const client = PulseIndex.create(
+  'api.usepulseindex.com:50051',
+  process.env.PULSEINDEX_API_KEY,
+  true,
+);
+```
+
+| Option | Env var | Default | Description |
+| --- | --- | --- | --- |
+| `endpoint` / `host` | `PULSEINDEX_ENDPOINT`, `PULSEINDEX_HOST` | `localhost:50051` | Engine `host:port` |
+| `apiKey` | `PULSEINDEX_API_KEY` | — | Sent as `x-api-key` and `Authorization: Bearer` |
+| `authorization` | `PULSEINDEX_AUTHORIZATION` | — | Overrides the Bearer token when set |
+| `tenantId` | `PULSEINDEX_TENANT_ID` | `''` (engine uses `default`) | Default tenant for index / search / delete |
+| `timeoutMs` | — | `5000` | Per-RPC deadline |
+| `ssl` | `PULSEINDEX_SSL` | `false` | Enable TLS |
+| `rootCerts` / `privateKey` / `certChain` | — | — | Optional custom TLS materials |
+| `poolSize` | — | `1` | Number of multiplexed gRPC clients |
+| `protoPath` | — | packaged `proto/engine.proto` | Override the proto file |
+| `channelOptions` | — | keepalive defaults | Extra `@grpc/grpc-js` channel options |
+
+The client sends your key as `x-api-key`, and also as `Authorization: Bearer` — either is accepted. Every indexing and query call carries `tenant_id`; an empty value means `"default"`.
+
+```ts
+const client = new PulseIndex({
+  endpoint: process.env.PULSEINDEX_HOST,
+  apiKey: process.env.PULSEINDEX_API_KEY,
+  tenantId: 'acme_corp',
+  timeoutMs: 5000,
+  ssl: true,
+  poolSize: 2,
+});
+```
+
+## Indexing
+
+`index()` accepts a string/number entity id plus a flat attribute object. Reserved keys (`price`, `tenantId`, `lat` / `lng`, `categories`, …) map onto dedicated fields; every other key becomes a namespaced term (`status:listed`, `amenities:parking`) you can filter on. Coordinates automatically add `geo:5:…` and `geo:6:…` tags.
+
+```ts
+await client.index('1001', {
+  categories: ['feature:pool'],
+  amenities: ['parking', 'gym'],
+  furnished: true,
+  price: 1500,
+  lat: 24.7136,
+  lng: 46.6753,
+});
+
+await client.batchIndex([
+  { id: '1002', attributes: { categories: ['feature:garden'], price: 900 } },
+  { entityId: 1003, categories: ['feature:pool'], price: 2000 },
+]);
+
+await client.delete('1001');
+```
+
+Low-level PHP-compatible helper:
+
+```ts
+await client.indexEntity(1001, ['feature:pool', 'amenity:parking'], 1500, 0, 'acme');
+```
+
+`entity_id` is a proto `uint64`. Pass a string when the id may exceed `Number.MAX_SAFE_INTEGER`.
+
+## QueryBuilder
+
+The engine evaluates MUST (AND), SHOULD (OR group, then AND), MUST_NOT, optional `price` ranges, and returns ids only. `QueryBuilder` is immutable: each chained call returns a new builder.
+
+```ts
+const query = client
+  .query()
+  .tenant('acme_corp')
+  .must('feature:pool')
+  .should(['category:villa', 'category:apartment'])
+  .mustNot('status:sold')
+  .range('price', 1000, 5000)
+  .withinRadius({ lat: 24.7136, lng: 46.6753, radiusKm: 5 })
+  .limit(50)
+  .offset(0);
+
+const page = await query.execute();
+```
+
+Equivalent object form:
+
+```ts
+await client.search({
+  tenantId: 'acme_corp',
+  must: 'feature:pool',
+  should: ['category:villa', 'category:apartment'],
+  mustNot: 'status:sold',
+  ranges: [{ field: 'price', min: 100000, max: 500000 }],
+  withinRadius: { lat: 41.0082, lng: 28.9784, radiusKm: 5 },
+  limit: 50,
+});
+```
+
+| Method | Effect |
+| --- | --- |
+| `tenant(id)` | Set `tenant_id` |
+| `must(attr \| attr[])` | MUST filters |
+| `should(attr \| attr[])` | SHOULD filters (OR group) |
+| `mustNot(attr \| attr[])` | MUST_NOT filters |
+| `range(field, min, max)` | Numeric range (currently `price`) |
+| `withinRadius(lat, lon, km)` / `withinRadius({ lat, lng, radiusKm })` | SHOULD geo covering |
+| `whereGeoHash(hash)` / `inGeoHash(hash)` | MUST exact geo cell |
+| `location(prefix)` | Coarse `location_prefix` |
+| `limit(n)` / `offset(n)` | Pagination (`0` = unlimited) |
+| `toRequest()` | Compile the proto-shaped payload |
+| `execute()` | Search via the bound client |
+
+## GeoHash usage
+
+Precision is chosen from radius, then covering cells are emitted as SHOULD `geo:{precision}:{hash}` tags:
+
+| Radius | Precision | Approximate cell |
+| --- | --- | --- |
+| ≤ 1.5 km | 6 | ~1.2 km × 0.6 km |
+| ≤ 8.0 km | 5 | ~4.9 km × 4.9 km |
+| > 8.0 km | 4 | ~39 km × 19 km |
+
+`GeoHash.neighborhood3x3()` returns the centre cell plus eight neighbors. `withinRadius()` uses intersecting covering cells (same algorithm as `pulseindex-php`) so oversized neighbors are not OR'd in.
+
+```ts
+import { GeoHash } from '@pulseindex/sdk';
+
+GeoHash.encode(42.6, -5.6, 5); // 'ezs42'
+GeoHash.tag('ezs42'); // 'geo:5:ezs42'
+GeoHash.encodeMultiTags(41.0082, 28.9784);
+GeoHash.neighborhood3x3('ezs42'); // centre + 8 neighbors
+query.whereGeoHash('ezs42'); // MUST geo:5:ezs42
+```
+
+Also available: `decode`, `decodeBounds`, `neighbor`, `neighbors`, `neighborhoodTags`, `optimalPrecisionForRadius`, `getCoveringHashes`, `encodeTag`, `haversineKm`.
+
+## Error handling
+
+All RPC failures wrap gRPC status codes. Catch the typed subclass that matches the failure mode:
+
+```ts
+import {
+  PulseIndexAuthError,
+  PulseIndexConnectionError,
+  PulseIndexQueryError,
+} from '@pulseindex/sdk';
+
+try {
+  await client.search(PulseIndex.query().must('feature:pool').limit(20));
+} catch (error) {
+  if (error instanceof PulseIndexAuthError) {
+    // UNAUTHENTICATED / PERMISSION_DENIED — check x-api-key
+  } else if (error instanceof PulseIndexConnectionError) {
+    // UNAVAILABLE / DEADLINE_EXCEEDED — engine down or timeout
+  } else if (error instanceof PulseIndexQueryError) {
+    // INVALID_ARGUMENT / RESOURCE_EXHAUSTED — bad query or capacity
+  } else {
+    throw error;
+  }
+}
+```
+
+| Class | Typical gRPC statuses |
+| --- | --- |
+| `PulseIndexError` | Base class (`code`, `grpcStatusCode`, `grpcDetails`) |
+| `PulseIndexConnectionError` | `UNAVAILABLE`, `DEADLINE_EXCEEDED`, `CANCELLED`, `ABORTED` |
+| `PulseIndexAuthError` | `UNAUTHENTICATED`, `PERMISSION_DENIED` |
+| `PulseIndexQueryError` | `INVALID_ARGUMENT`, `FAILED_PRECONDITION`, `RESOURCE_EXHAUSTED`, … |
+
+`client.health()` returns `false` instead of throwing when the channel is not ready.
+
+### Health
+
+`client.health()` is `true` only when the service can **serve reads**: the channel
+is ready and the standard health protocol reports `SERVING`. A reachable service
+that cannot currently answer queries reports `false`, so reachability alone is not
+treated as health.
+
+It returns `false` rather than throwing, which means unreachable and unavailable
+look the same. Use `servingStatus()` when you need to tell them apart:
+
+```ts
+import { SERVING_STATUS } from '@pulseindex/sdk';
+
+const status = await client.servingStatus();
+status === SERVING_STATUS.SERVING;       // ready for queries
+status === SERVING_STATUS.NOT_SERVING;   // reachable, not currently serving
+```
+
+`health()` needs no particular scope on your API key — it does not send one.
+
+If `health()` stays `false` for more than a few minutes, retry with backoff rather
+than failing your own requests immediately; if it persists, contact support.
+
+## API reference
+
+### `PulseIndex` / `PulseIndexClient`
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `new PulseIndex(config)` | client | Create a pooled gRPC client |
+| `PulseIndex.create(host, apiKey?, ssl?)` | client | Convenience constructor |
+| `PulseIndex.query()` | `QueryBuilder` | Unbound fluent query |
+| `client.query()` | `QueryBuilder` | Bound builder (`execute()` calls `search`) |
+| `client.search(query \| options)` | `SearchResponse` | Run `Search` |
+| `client.index(id, attributes)` | `{ success }` | Upsert one entity |
+| `client.batchIndex(entities)` | `{ indexedCount }` | Batch upsert |
+| `client.delete(id)` | `{ success }` | Soft-delete an entity |
+| `client.health()` | `boolean` | Whether the service is ready to answer queries |
+| `client.servingStatus()` | `number` | Readiness as a status code, when you need more than a boolean |
+| `client.close()` | `void` | Shut down the channel pool |
+
+`SearchResponse`:
+
+```ts
+{
+  matchedEntityIds: string[];
+  totalMatches: number;
+  executionTimeUs: number;
+}
+```
+
+## gRPC contract
+
+Service: `pulseindex.engine.v1.SearchEngineService`
+
+| RPC | Request | Response |
+| --- | --- | --- |
+| `IndexEntity` | `IndexEntityRequest` | `IndexEntityResponse` |
+| `BatchIndexEntities` | `BatchIndexEntitiesRequest` | `BatchIndexEntitiesResponse` |
+| `DeleteEntity` | `DeleteEntityRequest` | `DeleteEntityResponse` |
+| `Search` | `SearchQueryRequest` | `SearchQueryResponse` |
+
+`health()` reports whether the service is ready to answer queries. It needs no
+particular scope, so it works with any key.
+
+## License
+
+MIT