@pulseindex/sdk 2.0.0

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@pulseindex/sdk",
+  "version": "2.0.0",
+  "description": "Official Node.js & TypeScript SDK for PulseIndex — hosted search and filtering for large entity sets",
+  "license": "MIT",
+  "author": "PulseIndex",
+  "keywords": [
+    "pulseindex",
+    "sdk",
+    "grpc",
+    "search",
+    "indexing",
+    "geohash",
+    "typescript",
+    "nodejs"
+  ],
+  "homepage": "https://usepulseindex.com",
+  "bugs": {
+    "url": "https://usepulseindex.com/support"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./proto/engine.proto": "./proto/engine.proto",
+    "./proto/health.proto": "./proto/health.proto"
+  },
+  "files": [
+    "dist",
+    "proto",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "check:proto": "node scripts/check-proto.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.12.6",
+    "@grpc/proto-loader": "^0.7.13"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  }
+}

package/proto/engine.proto

@@ -0,0 +1,191 @@
+// PulseIndex Engine gRPC API
+//
+// Package: pulseindex.engine.v1
+//
+// The wire contract for the PulseIndex service. Client SDKs generate stubs
+// directly from this file. Queries return matching entity IDs, which the caller
+// hydrates from its own primary data store — record contents are never sent
+// here and are never stored by the service.
+//
+// Authentication (transport metadata, not proto fields):
+//   - Header `x-api-key: <key>`  OR
+//   - Header `authorization: Bearer <key>`
+//   Keys are issued and revoked from the PulseIndex dashboard.
+//
+// Multi-tenancy:
+//   Every mutating / query RPC that touches index state carries `tenant_id`.
+//   Empty `tenant_id` is normalized server-side to `"default"`. Tenants are
+//   fully isolated from one another.
+//
+syntax = "proto3";
+
+package pulseindex.engine.v1;
+
+// SearchEngineService is the PulseIndex query and indexing API.
+service SearchEngineService {
+  // IndexEntity upserts a single entity into the tenant's index.
+  // Re-indexing the same entity_id within a tenant replaces its attributes and
+  // clears any soft-delete for that id.
+  rpc IndexEntity (IndexEntityRequest) returns (IndexEntityResponse);
+
+  // BatchIndexEntities indexes many entities in one RPC.
+  // Processing is ordered; capacity / auth failures abort the batch.
+  rpc BatchIndexEntities (BatchIndexEntitiesRequest) returns (BatchIndexEntitiesResponse);
+
+  // DeleteEntity soft-deletes an entity inside a tenant.
+  // The entity id is excluded from subsequent Search results for that tenant.
+  rpc DeleteEntity (DeleteEntityRequest) returns (DeleteEntityResponse);
+
+  // Search applies the boolean filters (MUST / SHOULD / MUST_NOT) plus optional
+  // numeric range predicates and returns matching entity IDs only.
+  // When `limit` > 0, `total_matches` may be approximate; it is exact when
+  // `limit` is 0.
+  rpc Search (SearchQueryRequest) returns (SearchQueryResponse);
+
+
+
+}
+
+// ---------------------------------------------------------------------------
+// Indexing
+// ---------------------------------------------------------------------------
+
+// IndexEntityRequest describes a single entity to upsert.
+// No record content (name, description, PII) is sent or stored — only the
+// attributes you want to filter on.
+message IndexEntityRequest {
+  // Stable application-level entity identifier (e.g. listing id).
+  // Dense, ascending ids index and query most efficiently.
+  uint64 entity_id = 1;
+
+  // Optional geohash-style location prefix. Matches the `location_prefix`
+  // filter on Search, and `location:<prefix>` as an attribute.
+  // Use 0 to omit location indexing.
+  uint64 location_prefix = 2;
+
+  // Numeric price (or similar scalar), filterable through RangePredicate.
+  uint32 price = 3;
+
+  // Attribute tokens already namespaced by the client, e.g.:
+  //   "feature:pool", "furnishing:full", "amenity:parking"
+  // Tokens are matched exactly; they are never stored as readable text.
+  repeated string categories = 4;
+
+  // Tenant / namespace isolation key. Empty string → server uses "default".
+  // Two tenants may reuse the same entity_id without colliding.
+  string tenant_id = 5;
+}
+
+// IndexEntityResponse acknowledges a successful upsert.
+message IndexEntityResponse {
+  // True when the entity was accepted into the index.
+  // Capacity violations return gRPC RESOURCE_EXHAUSTED instead.
+  bool success = 1;
+}
+
+// BatchIndexEntitiesRequest wraps multiple IndexEntityRequest messages.
+message BatchIndexEntitiesRequest {
+  // Entities to index. Each entry may specify its own tenant_id.
+  repeated IndexEntityRequest entities = 1;
+}
+
+// BatchIndexEntitiesResponse reports how many entities were indexed.
+message BatchIndexEntitiesResponse {
+  // Number of entities successfully indexed in this batch.
+  uint32 indexed_count = 1;
+}
+
+// ---------------------------------------------------------------------------
+// Deletion
+// ---------------------------------------------------------------------------
+
+// DeleteEntityRequest soft-deletes one entity within a tenant.
+message DeleteEntityRequest {
+  // Entity id to delete.
+  uint64 entity_id = 1;
+
+  // Tenant that owns the entity. Empty → "default".
+  string tenant_id = 2;
+}
+
+// DeleteEntityResponse reports whether a live entity was deleted.
+message DeleteEntityResponse {
+  // True if the entity was present and marked deleted; false if unknown / already deleted.
+  bool success = 1;
+}
+
+// ---------------------------------------------------------------------------
+// Search predicates
+// ---------------------------------------------------------------------------
+
+// FilterPredicate is a categorical / attribute filter.
+message FilterPredicate {
+  // How this predicate combines with the matches accumulated so far.
+  enum Operation {
+    // Conjunction: narrows the current match set.
+    MUST = 0;
+    // Disjunction group: SHOULD predicates are OR'd, then narrow the match set.
+    SHOULD = 1;
+    // Exclusion: removes matches carrying this attribute.
+    MUST_NOT = 2;
+  }
+
+  // How this predicate combines with the current match set.
+  Operation op = 1;
+
+  // Attribute token identical to those used at index time, e.g. "feature:pool".
+  string attribute = 2;
+}
+
+// RangePredicate filters a continuous numeric field to an inclusive range.
+message RangePredicate {
+  // Numeric field name. Currently supported: "price".
+  string field = 1;
+
+  // Inclusive lower bound of the requested range.
+  uint32 min_val = 2;
+
+  // Inclusive upper bound of the requested range.
+  uint32 max_val = 3;
+}
+
+// ---------------------------------------------------------------------------
+// Search
+// ---------------------------------------------------------------------------
+
+// SearchQueryRequest executes a filtered search inside one tenant.
+message SearchQueryRequest {
+  // Optional location constraint (0 = no location filter).
+  // When non-zero, only entities indexed with that location_prefix match.
+  uint64 location_prefix = 1;
+
+  // Attribute predicates (MUST / SHOULD / MUST_NOT). Order does not affect the
+  // result.
+  repeated FilterPredicate filters = 2;
+
+  // Optional numeric range filters (e.g. price between min_val and max_val).
+  repeated RangePredicate ranges = 3;
+
+  // Maximum number of entity IDs to return.
+  // 0 means no limit, and makes `total_matches` exact.
+  uint32 limit = 4;
+
+  // Number of matches to skip before collecting results (pagination).
+  uint32 offset = 5;
+
+  // Tenant / namespace to search. Empty → "default".
+  string tenant_id = 6;
+}
+
+// SearchQueryResponse returns matched ids and timing metadata.
+message SearchQueryResponse {
+  // Entity IDs that satisfied all predicates (after offset/limit).
+  // Caller hydrates full records from the primary data store.
+  repeated uint64 matched_entity_ids = 1;
+
+  // Number of matches. Exact when `limit` is 0; may be approximate otherwise.
+  uint32 total_matches = 2;
+
+  // Server-side execution time in microseconds (excludes network RTT).
+  uint64 execution_time_us = 3;
+}

package/proto/health.proto

@@ -0,0 +1,32 @@
+// The standard gRPC health checking protocol, as served by the engine.
+//
+// This is a verbatim subset of grpc/health/v1/health.proto — only `Check` is
+// used, so the streaming `Watch` RPC is omitted. It is vendored rather than
+// pulled from a package because it is a frozen protocol: it has not changed
+// since 2017, and a dependency for eleven lines is not worth the supply chain.
+//
+// It reports whether the service is ready to answer queries, and needs no
+// particular scope on the API key.
+
+syntax = "proto3";
+
+package grpc.health.v1;
+
+message HealthCheckRequest {
+  // Empty string means the health of the server as a whole.
+  string service = 1;
+}
+
+message HealthCheckResponse {
+  enum ServingStatus {
+    UNKNOWN = 0;
+    SERVING = 1;
+    NOT_SERVING = 2;
+    SERVICE_UNKNOWN = 3;
+  }
+  ServingStatus status = 1;
+}
+
+service Health {
+  rpc Check(HealthCheckRequest) returns (HealthCheckResponse);
+}