@kairos-es/feed-algolia 0.0.0-stage → 0.0.0

package/dist/dts-esm/classify.d.ts

@@ -0,0 +1,101 @@
+/**
+ * How an Algolia answer becomes one of the feed's three sink failures.
+ *
+ * The driver's whole behaviour on failure follows from which of the three a sink
+ * names (`@kairos-es/feed`'s `errors.ts` owns that), so this mapping is the most
+ * consequential thing in the package and it is kept pure, in one place, and tested
+ * on its own. The rules:
+ *
+ * - **A 429 is `SinkRetryable`**, carrying `Retry-After` when Algolia sends one,
+ *   so the driver backs off no less than Algolia asked — UNLESS its message names
+ *   a QUOTA rather than a rate: Algolia answers 429 for an application over its
+ *   record quota or its indexing file-size allowance too, and neither lifts by
+ *   waiting, so retrying would only hold the feed until supervision reported it
+ *   stalled, with Algolia's reason lost. Such a 429 is `SinkHalted`, carrying
+ *   Algolia's message. The wordings recognised are {@link QUOTA_429}; a 429 whose
+ *   wording is not among them stays retryable, which is the safe side to err on.
+ * - **Every 5xx is `SinkRetryable`, and so is a 1xx or 3xx**, a status no call
+ *   here expects and one the transport has already tried on every host, as the
+ *   official client does. A transport failure — no answer at all — is retryable
+ *   too: the request may never have arrived, and resending is safe because every
+ *   write this sink makes is a full-record replace or a delete.
+ * - **A 400 that names an `objectID` in the batch is `SinkRejected` for that key.**
+ *   Algolia refuses a whole batch for one bad record, and names the record in its
+ *   message (`… objectID=<id> …`). Parking just that key lets the driver send the
+ *   rest again without it, which is the difference between one record missing from
+ *   search and the whole feed stopping. The key has to be one the batch carried: an
+ *   id the batch did not send is not a record the driver can park, so such an
+ *   answer falls through to the next rule. The message does not delimit the id, and
+ *   a feed key may hold a space, a comma or anything else, so the id is not parsed
+ *   out of the message: the batch's own keys are matched against what follows
+ *   `objectID=` (`objectIdNamedIn`).
+ * - **Every other 4xx is `SinkHalted`.** Bad credentials, a key without the right
+ *   ACL, an index name Algolia will not accept, a request this package built wrong:
+ *   none of them is mended by sending again, so the worker stops and supervision
+ *   reports it.
+ *
+ * Nothing here reads the request, and nothing here sees a header but `Retry-After`,
+ * so no classification can carry the admin key into a reason string.
+ */
+import type { FeedKey } from '@kairos-es/feed';
+import { SinkHalted, SinkRejected, SinkRetryable } from '@kairos-es/feed';
+import { Duration, Option } from 'effect';
+/** Every failure an Algolia call can end in, already in the feed's vocabulary. */
+export type AlgoliaFailure = SinkRetryable | SinkRejected | SinkHalted;
+/** An Algolia answer that was not a success, reduced to what classifying needs. */
+export interface AlgoliaErrorAnswer {
+    readonly status: number;
+    /** Algolia's `message`, or the raw body when it sent none. */
+    readonly message: string;
+    /** The `Retry-After` header, verbatim, when there was one. */
+    readonly retryAfter: Option.Option<string>;
+}
+/** What the call was, for the reason string: never its headers. */
+export interface AlgoliaCallLabel {
+    readonly method: string;
+    readonly path: string;
+}
+/**
+ * The key of `batchKeys` an Algolia error message names, when it names one.
+ *
+ * Algolia's record-level refusals all carry `objectID=<id>` (the record-too-big
+ * message is the common one), with nothing marking where the id ends. So each
+ * batch key is tried against the text after each `objectID=`, and it matches when
+ * that text starts with the key and the key is followed by the end of the message,
+ * a space or punctuation; the longest key that matches wins, so of `big` and
+ * `big one` the message `objectID=big one is too big` names the second.
+ */
+export declare const objectIdNamedIn: (message: string, batchKeys: ReadonlySet<FeedKey>) => Option.Option<FeedKey>;
+/**
+ * The 429 wordings that name a quota, not a rate, matched case-insensitively
+ * anywhere in Algolia's message: an application over its record quota, or over
+ * its allowance of indexing by file size. See the module doc for why each halts.
+ */
+export declare const QUOTA_429: ReadonlyArray<RegExp>;
+/**
+ * `Retry-After` as a duration, given the current time.
+ *
+ * The header is either a whole number of seconds or an HTTP date. A date is turned
+ * into a wait against `now`, which the caller reads from `Clock` so a test's
+ * `TestClock` governs it; a date already past is a wait of zero. Anything else is
+ * ignored rather than guessed at, and the driver's own back-off applies.
+ */
+export declare const parseRetryAfter: (header: string, nowMillis: number) => Option.Option<Duration.Duration>;
+/**
+ * Classify an Algolia error answer; see the module doc for the rules.
+ *
+ * `batchKeys` is the set of keys the request carried, empty for a call that sends
+ * no records, so only a write can ever produce a `SinkRejected`.
+ */
+export declare const classifyAnswer: (call: AlgoliaCallLabel, answer: AlgoliaErrorAnswer, batchKeys: ReadonlySet<FeedKey>, nowMillis: number) => AlgoliaFailure;
+/**
+ * A request that got no answer at all. Retryable: see the module doc for why a
+ * resend is safe.
+ */
+export declare const transportFailure: (call: AlgoliaCallLabel, detail: string) => AlgoliaFailure;
+/**
+ * An answer this package cannot read: a success whose body is not the shape
+ * Algolia documents. Halted, because sending again will get the same body back.
+ */
+export declare const unreadableAnswer: (call: AlgoliaCallLabel, detail: string) => AlgoliaFailure;
+//# sourceMappingURL=classify.d.ts.map

package/dist/dts-esm/classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../src/classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACzE,OAAO,EAAY,QAAQ,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEnD,kFAAkF;AAClF,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,YAAY,GAAG,UAAU,CAAA;AAEtE,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;CAC3C;AAED,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAOD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,MAAM,EACf,WAAW,WAAW,CAAC,OAAO,CAAC,KAC9B,MAAM,CAAC,MAAM,CAAC,OAAO,CAiBvB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,aAAa,CAAC,MAAM,CAA4B,CAAA;AAExE;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAC1B,QAAQ,MAAM,EACd,WAAW,MAAM,KAChB,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAajC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,gBAAgB,EACtB,QAAQ,kBAAkB,EAC1B,WAAW,WAAW,CAAC,OAAO,CAAC,EAC/B,WAAW,MAAM,KAChB,cAiCF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAM,gBAAgB,EACtB,QAAQ,MAAM,KACb,cAGC,CAAA;AAEJ;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAM,gBAAgB,EACtB,QAAQ,MAAM,KACb,cAGC,CAAA"}

package/dist/dts-esm/identifiers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The Algolia sink's branded identifiers.
+ *
+ * Three values cross this package's boundary that would otherwise be bare
+ * strings and numbers, and each is easy to pass in the place of another: an
+ * application id where an index name belongs, a feed key where an index name
+ * belongs, a task id from one index polled against another. Branding them is the
+ * repository's standing rule for a domain identifier, and here it is also what
+ * keeps a `Receipt` — an index and a task id — from being assembled by hand out of
+ * values that never belonged together.
+ */
+import { Schema } from 'effect';
+/**
+ * The Algolia application id: the first half of the credentials, and the name of
+ * the application's hosts. Not a secret — it is sent beside every search a browser
+ * makes — so it is a plain branded string, unlike the admin key.
+ */
+export declare const AlgoliaAppId: Schema.brand<Schema.String, "AlgoliaAppId">;
+export type AlgoliaAppId = typeof AlgoliaAppId.Type;
+/**
+ * The name of an Algolia index. The sink's SERVED index is one; a resync builds into
+ * another, named after the served one, the generation it rebuilds and the attempt.
+ */
+export declare const AlgoliaIndexName: Schema.brand<Schema.String, "AlgoliaIndexName">;
+export type AlgoliaIndexName = typeof AlgoliaIndexName.Type;
+/**
+ * An Algolia task id: what every write returns, and what `getTask` is polled with
+ * until the write is published. A task belongs to the index it was issued on, and
+ * is polled there and nowhere else — which is why a receipt carries the index
+ * beside it.
+ */
+export declare const AlgoliaTaskId: Schema.brand<Schema.Number, "AlgoliaTaskId">;
+export type AlgoliaTaskId = typeof AlgoliaTaskId.Type;
+//# sourceMappingURL=identifiers.d.ts.map

package/dist/dts-esm/identifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.d.ts","sourceRoot":"","sources":["../../src/identifiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B;;;;GAIG;AACH,eAAO,MAAM,YAAY,6CAGxB,CAAA;AACD,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;AAEnD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,iDAG5B,CAAA;AACD,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,aAAa,8CAGzB,CAAA;AACD,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA"}

package/dist/dts-esm/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @kairos-es/feed-algolia — a `FeedSink` onto an Algolia index, with both of the
+ * port's optional parts: a `FeedResync` that rebuilds into a fresh index and moves
+ * it over the served one, and a `FeedReconcile` that lists the served index's ids.
+ *
+ * It talks to Algolia's REST API through `effect`'s own `HttpClient`, so it peers
+ * `effect` and `@kairos-es/feed` and nothing else, and the application chooses the
+ * HTTP transport by providing the client — `FetchHttpClient.layer` from
+ * `effect/http`, say.
+ *
+ * Where each part's argument lives:
+ *
+ * - `makeAlgoliaSink` (`sink.ts`): the steady state, resync and reconcile, and how
+ *   `confirm` waits.
+ * - Encoding and the size pre-check (`records.ts`): why only full-record writes,
+ *   and why oversized records are refused before they are sent.
+ * - Error classification (`classify.ts`): which Algolia answers are retryable,
+ *   which refuse one record, and which stop the worker.
+ * - The REST calls (`rest.ts`): why no SDK, the host failover kept from it, and
+ *   how the admin key is kept out of anything printed.
+ *
+ * Wiring:
+ *
+ * ```ts
+ * const sink = yield* makeAlgoliaSink({
+ *   name: SinkName.make('search'),
+ *   appId: AlgoliaAppId.make(config.appId),
+ *   adminKey: config.adminKey, // a Redacted<string>, from the application's config
+ *   index: AlgoliaIndexName.make('courses'),
+ *   doc: CourseDoc,
+ * }).pipe(Effect.provide(FetchHttpClient.layer))
+ * yield* Effect.forkScoped(runFeedSync({ source, sink, store }))
+ * ```
+ */
+export { AlgoliaAppId, AlgoliaIndexName, AlgoliaTaskId, } from './identifiers.js';
+export { DEFAULT_MAX_RECORD_BYTES } from './records.js';
+export type { AlgoliaConnection, AlgoliaTimeouts } from './rest.js';
+export { type AlgoliaReceipt, type AlgoliaSinkOptions, type AlgoliaTaskPolling, makeAlgoliaSink, } from './sink.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/dts-esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,aAAa,GACd,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAA;AACpD,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAA;AAChE,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,eAAe,GAChB,MAAM,QAAQ,CAAA"}

package/dist/dts-esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/dts-esm/records.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Turning a batch of feed changes into Algolia batch operations, and refusing the
+ * records Algolia would refuse BEFORE they are sent.
+ *
+ * ## Full-record replace, and nothing partial
+ *
+ * An upsert is `addObject` with the record's `objectID` set to the feed key, which
+ * replaces whatever Algolia held under that id; a delete is `deleteObject`. Both
+ * leave the index the same however many times they are sent, which is the
+ * idempotence the driver relies on when it resends a batch it could not confirm.
+ * Algolia's partial operations (`partialUpdateObject`, the built-in `Increment`
+ * and its kin) do not: applied twice they apply twice. They are never used.
+ *
+ * The key is written LAST, over the encoded document, so a document that carries an
+ * `objectID` field of its own cannot point a record at another key.
+ *
+ * ## Why oversized records are refused here
+ *
+ * Algolia refuses a whole `batch` when one record in it is over the plan's record
+ * size limit. Its answer does name the record, and `classify.ts` turns that into a
+ * rejection of that one key — but only after a round trip that wrote nothing, and
+ * only for the first oversized record the batch held. Checking every record's size
+ * up front rejects all of them at once, so the driver's resend of the rest goes
+ * through first time. The 400 path stays as the backstop for a limit configured
+ * higher than the plan's.
+ *
+ * The size is the record's JSON in UTF-8 bytes, `objectID` included, which is how
+ * Algolia measures it. The default limit is the smallest Algolia plan's (10 KB);
+ * an application on a larger plan raises it.
+ *
+ * ## A document that does not encode
+ *
+ * The document schema is the read model's, and a document it cannot encode — or one
+ * that encodes to something other than a JSON object, which is all an Algolia
+ * record can be — is a defect in the read model, not a record the sink refuses. It
+ * dies, loudly, rather than being parked where nobody looks.
+ */
+import { type FeedChange, type FeedKey, SinkRejected } from '@kairos-es/feed';
+import { Effect, Schema } from 'effect';
+import type { NonEmptyReadonlyArray } from 'effect/Array';
+import type { BatchOperation } from './rest.js';
+/** The smallest Algolia plan's record size limit, in bytes. */
+export declare const DEFAULT_MAX_RECORD_BYTES = 10000;
+/** A record's size as Algolia measures it: its JSON, in UTF-8 bytes. */
+export declare const recordBytes: (record: Readonly<Record<string, unknown>>) => number;
+/** A batch ready to send: its operations, and the keys it carries. */
+export interface EncodedBatch {
+    readonly operations: ReadonlyArray<BatchOperation>;
+    readonly keys: ReadonlySet<FeedKey>;
+}
+/**
+ * Encode a batch, failing `SinkRejected` with EVERY oversized key when there is
+ * one; see the module doc.
+ */
+export declare const encodeBatch: <D, I>(doc: Schema.Codec<D, I>, maxRecordBytes: number, batch: NonEmptyReadonlyArray<FeedChange<D>>) => Effect.Effect<EncodedBatch, SinkRejected>;
+//# sourceMappingURL=records.d.ts.map

package/dist/dts-esm/records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../src/records.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC7E,OAAO,EAAgB,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACrD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAE5C,+DAA+D;AAC/D,eAAO,MAAM,wBAAwB,QAAS,CAAA;AAI9C,wEAAwE;AACxE,eAAO,MAAM,WAAW,GACtB,QAAQ,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KACxC,MAAoD,CAAA;AAEvD,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,cAAc,CAAC,CAAA;IAClD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;CACpC;AAKD;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAAE,CAAC,EAC9B,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EACvB,gBAAgB,MAAM,EACtB,OAAO,qBAAqB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAC1C,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,CAuCvC,CAAA"}

package/dist/dts-esm/rest.d.ts

@@ -0,0 +1,215 @@
+/**
+ * The slice of Algolia's REST API this sink speaks, over `effect`'s own
+ * `HttpClient`.
+ *
+ * ## Why no SDK
+ *
+ * The surface the sink needs is eight calls — `batch`, `getTask`, `operationIndex`
+ * (copy and move), `deleteIndex`, `browse`, `listIndices`, and a settings read and
+ * write, which is how a resync target is made to exist and marked as its attempt's
+ * own — and each is one JSON request. Peering `algoliasearch` would bring a large
+ * non-Effect dependency for that, and its retries would sit underneath the feed
+ * driver's own supervision, which already owns retrying. Over `HttpClient` the
+ * sink is Effect-native, adds no peer beyond `effect`, and is faked in tests by a
+ * stub client with no network at all.
+ *
+ * ## Host failover
+ *
+ * The one piece of the SDK's transport kept here is the part the driver cannot do
+ * for itself: trying ANOTHER HOST. Algolia serves an application from
+ * `<appId>.algolia.net` and documents three fallbacks on separate infrastructure,
+ * `<appId>-1.algolianet.com` to `<appId>-3.algolianet.com`, to be tried when the
+ * first does not answer. A request that gets no answer (a transport failure, or no
+ * answer within its timeout), a 5xx, or a 1xx or 3xx — a status no call here
+ * expects, on which the official JavaScript client tries the next host too — is
+ * sent again at once to the next host, and only when every host it tried has
+ * failed is the call `SinkRetryable`, carrying the last host's failure. Without
+ * it, one unreachable host would hold the feed in the driver's back-off for as
+ * long as the host stayed down, with three healthy hosts unasked.
+ *
+ * - Hosts are STATEFUL, one state per client and so per sink, in the shape the
+ *   official JavaScript client gives them. A host that failed in one of those ways
+ *   is marked DOWN for two minutes, by `Clock`, and skipped by every call while it
+ *   is down; a host that answers is marked up again. Without that memory a primary
+ *   that drops packets would cost a whole timeout on EVERY call, each `getTask`
+ *   poll included, so a single wait for a task could spend its whole
+ *   `taskPolling.timeout` on the dead host. When every host is down, every host is
+ *   tried again, in order, rather than none.
+ * - The fallbacks are SHUFFLED, once, when the client is built, from Effect's
+ *   `Random`, so many workers do not all fail over onto the same host; the primary
+ *   goes first whenever it is up.
+ * - Each hand-off to the next host is logged at DEBUG level, with the call, the
+ *   host that failed, the host tried next and why. A call that lands after a
+ *   failover looks like any other, so that line is the only trace one leaves.
+ *   Hosts carry the application id, which is not a secret; the key travels in a
+ *   header and reaches no log.
+ * - Three timeouts, as the official client has: `connect`, `read` and `write`,
+ *   defaulting to its 2, 5 and 30 seconds. A read is a `GET` or a `browse`, and
+ *   every other call is a write. `HttpClient` does not show this module the moment
+ *   a connection is made, so one request's budget on one host is `connect` plus
+ *   `read`, or `connect` plus `write`, over the whole exchange. A transport that
+ *   enforces a connect timeout of its own fails sooner, and that failure fails
+ *   over the same way.
+ * - Every call uses the same list, reads included. The SDK sends reads to
+ *   `<appId>-dsn.algolia.net` first, which is the search-serving network; every
+ *   read here is an admin read (a task's status, a listing, a settings read, a
+ *   browse for reconcile) that wants the cluster the writes went to.
+ * - A 429 is NOT retried on another host: it is the application's rate limit or
+ *   quota, not a host's health (`classify.ts` owns which). Nor is any other 4xx,
+ *   which another host would answer the same.
+ * - A request can be sent more than once this way, and that is safe for the
+ *   reason every resend here is (`classify.ts`): every write is a full-record
+ *   replace, a delete, an index operation or a settings write, each of which
+ *   leaves the application the same however often it lands.
+ * - The worst case for one call is therefore its budget times the number of hosts
+ *   that are up when it starts.
+ * - An explicit `host` turns failover OFF: the caller has named the one place to
+ *   talk to (a proxy, a test double), and there are no fallbacks of it to guess.
+ *   That one host is never skipped, since every host being down tries it again.
+ *
+ * ## The admin key
+ *
+ * It is held as `Redacted` and unwrapped only into the request header, at the
+ * moment the request is built. Two things keep it out of anything printed: no
+ * failure this module produces carries the request or its headers — only the
+ * method, the path and Algolia's own message (`classify.ts`) — and every request
+ * runs with Algolia's key header added to the names `effect`'s `Headers` redact,
+ * so a request that is logged or traced by something further down shows the
+ * header as redacted.
+ *
+ * ## Not found
+ *
+ * Three of the calls meet a missing index as an ordinary outcome rather than a
+ * failure — dropping a leftover resync index that is not there, browsing an index
+ * that does not exist yet, reading the settings of an index that does not exist —
+ * so they answer a 404 as `Option.none()` instead of a `SinkHalted`. Every other
+ * call halts on a 404, with Algolia's own message in the reason. An index
+ * operation is one of those: Algolia documents a copy of a missing source as
+ * creating an empty destination, and a move of one as ignored without an error,
+ * so neither is a 404 (the sink's `publish` owns what that costs). A 404 is never
+ * failed over: another host would answer the same.
+ */
+import type { FeedKey } from '@kairos-es/feed';
+import { Duration, Effect, Option, Redacted } from 'effect';
+import { HttpClient, type HttpMethod } from 'effect/http';
+import { type AlgoliaFailure } from './classify.js';
+import { type AlgoliaAppId, type AlgoliaIndexName, AlgoliaTaskId } from './identifiers.js';
+/** Where and as whom the sink talks to Algolia. */
+export interface AlgoliaConnection {
+    readonly appId: AlgoliaAppId;
+    /** The admin API key. Never logged; see the module doc. */
+    readonly adminKey: Redacted.Redacted<string>;
+    /**
+     * ONE base URL to send every call to, with no failover. Leave it unset to talk
+     * to Algolia itself: `https://<appId>.algolia.net`, failing over to the three
+     * documented fallback hosts (see the module doc). Set it for a proxy or a test
+     * double, whose fallbacks there is no way to know.
+     */
+    readonly host?: string;
+    /**
+     * How long one request to one host may take before it counts as unanswered,
+     * that host is marked down, and the next is tried; see the module doc.
+     */
+    readonly timeouts?: AlgoliaTimeouts;
+}
+/**
+ * The three per-host timeouts, with the official JavaScript client's defaults. A
+ * request's budget on one host is `connect` plus `read` for a read, or `connect`
+ * plus `write` for a write; see the module doc for why they are added.
+ */
+export interface AlgoliaTimeouts {
+    /** Default 2 seconds. */
+    readonly connect?: Duration.Input;
+    /** For a `GET` or a `browse`. Default 5 seconds. */
+    readonly read?: Duration.Input;
+    /** For every other call. Default 30 seconds. */
+    readonly write?: Duration.Input;
+}
+/** One batch operation, as Algolia's `batch` takes it. Full-record writes only. */
+export type BatchOperation = {
+    readonly action: 'addObject';
+    readonly body: Readonly<Record<string, unknown>>;
+} | {
+    readonly action: 'deleteObject';
+    readonly body: {
+        readonly objectID: string;
+    };
+};
+/** What an index-level `operationIndex` call asks for. */
+export interface IndexOperation {
+    readonly operation: 'copy' | 'move';
+    readonly destination: AlgoliaIndexName;
+    readonly scope?: ReadonlyArray<'settings' | 'synonyms' | 'rules'>;
+}
+/** One page of a `browse`: the ids on it, and the cursor to the next, if any. */
+export interface BrowsePage {
+    readonly objectIDs: ReadonlyArray<string>;
+    readonly cursor: Option.Option<string>;
+}
+/** One page of `listIndices`: the index names on it, and whether more follow. */
+export interface IndexListPage {
+    readonly names: ReadonlyArray<string>;
+    readonly more: boolean;
+}
+/** One raw call: everything the typed calls below are built from. */
+export interface AlgoliaCall {
+    readonly method: HttpMethod.HttpMethod;
+    /** The path, already encoded: `/1/indexes/<name>/...`. */
+    readonly path: string;
+    readonly body?: unknown;
+    /** The keys the request carries, so a 400 naming one can be a rejection. */
+    readonly batchKeys?: ReadonlySet<FeedKey>;
+    /**
+     * A read whose method is not `GET` (a `browse`), so it gets the read timeout.
+     * Every `GET` is a read already.
+     */
+    readonly read?: true;
+}
+/**
+ * Where a task stands, as a caller that tolerates a missing index sees it: still
+ * running, published, or unanswerable because its index does not exist.
+ */
+export type AlgoliaTaskState = 'pending' | 'published' | 'indexMissing';
+/** The Algolia calls the sink makes. Every failure is already classified. */
+export interface AlgoliaRest {
+    /** A raw call; `Option.none()` on a 404. Exposed for the package's own tests. */
+    readonly call: (call: AlgoliaCall) => Effect.Effect<Option.Option<unknown>, AlgoliaFailure>;
+    readonly batch: (index: AlgoliaIndexName, operations: ReadonlyArray<BatchOperation>, batchKeys: ReadonlySet<FeedKey>) => Effect.Effect<AlgoliaTaskId, AlgoliaFailure>;
+    readonly taskPublished: (index: AlgoliaIndexName, taskID: AlgoliaTaskId) => Effect.Effect<boolean, AlgoliaFailure>;
+    /**
+     * `taskPublished`, as a state, with a 404 — Algolia's answer to `getTask` on an
+     * index that does not exist — as `'indexMissing'` rather than a halt, for a
+     * caller that has another way to learn what the task did.
+     */
+    readonly taskStateUnlessIndexMissing: (index: AlgoliaIndexName, taskID: AlgoliaTaskId) => Effect.Effect<AlgoliaTaskState, AlgoliaFailure>;
+    /**
+     * A copy or a move. Algolia answers a missing source with a task too: a copy
+     * creates an empty destination, and a move does nothing (see the module doc).
+     */
+    readonly operation: (source: AlgoliaIndexName, operation: IndexOperation) => Effect.Effect<AlgoliaTaskId, AlgoliaFailure>;
+    /** `Option.none()` when the index does not exist. */
+    readonly deleteIndex: (index: AlgoliaIndexName) => Effect.Effect<Option.Option<AlgoliaTaskId>, AlgoliaFailure>;
+    /** An index's settings; `Option.none()` when the index does not exist. */
+    readonly readSettings: (index: AlgoliaIndexName) => Effect.Effect<Option.Option<Readonly<Record<string, unknown>>>, AlgoliaFailure>;
+    /**
+     * A settings write of the settings named, and only those; a `null` resets one
+     * to its default. Algolia creates an index on a settings write, so this is also
+     * how an index is made to exist without a record.
+     */
+    readonly writeSettings: (index: AlgoliaIndexName, settings: Readonly<Record<string, unknown>>) => Effect.Effect<AlgoliaTaskId, AlgoliaFailure>;
+    /**
+     * One page of the application's index names, `page` counting from 0. Every
+     * index the key may see is listed, so a caller filters by name.
+     */
+    readonly listIndexNames: (page: number, hitsPerPage: number) => Effect.Effect<IndexListPage, AlgoliaFailure>;
+    /** A missing index browses as one empty last page. */
+    readonly browseObjectIds: (index: AlgoliaIndexName, cursor: Option.Option<string>, hitsPerPage: number) => Effect.Effect<BrowsePage, AlgoliaFailure>;
+}
+/** The path of an index, or of something under it. */
+export declare const indexPath: (index: AlgoliaIndexName, rest?: string) => string;
+/**
+ * Build the REST client over the `HttpClient` in context. The client is captured
+ * here, so every call the sink makes later needs nothing from its caller.
+ */
+export declare const makeAlgoliaRest: (connection: AlgoliaConnection) => Effect.Effect<AlgoliaRest, never, HttpClient.HttpClient>;
+//# sourceMappingURL=rest.d.ts.map

package/dist/dts-esm/rest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest.d.ts","sourceRoot":"","sources":["../../src/rest.ts"],"names":[],"mappings":"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"}