@tsdmarc/opensearch 0.0.0-stage → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,233 @@
+import { AggregateReport, FailureReport, SMTPTLSReport } from "tsdmarc";
+import { Client } from "@opensearch-project/opensearch";
+interface IndexMapping {
+  readonly date_detection: boolean;
+  readonly properties: Record<string, unknown>;
+}
+/** A query clause, as the DSL's `Q()` renders it. */
+type Query = Record<string, unknown>;
+interface DocumentMappings {
+  readonly aggregate: {
+    properties: Record<string, unknown>;
+  };
+  readonly failure: {
+    properties: Record<string, unknown>;
+  };
+  readonly smtpTls: {
+    properties: Record<string, unknown>;
+  };
+}
+/**
+ * The mappings parsedmarc's document classes declare. `createIndexes()`
+ * does not install them (neither does parsedmarc): the shipped dashboards
+ * rely on dynamic mapping. They are exported for reference and for users
+ * who manage index templates themselves.
+ */
+export declare const DOCUMENT_MAPPINGS: DocumentMappings;
+/** Raised when an OpenSearch error occurs. */
+export declare class OpenSearchError extends Error {
+  override name: string;
+}
+/** Raised when a report to be saved matches an existing report. */
+export declare class AlreadySaved extends Error {
+  override name: string;
+}
+/** The backfill queries and scripts migrateIndexes() submits. */
+export declare const BACKFILL: {
+  readonly aggregateQuery: Query;
+  readonly aggregateScript: string;
+  readonly smtpTlsQuery: Query;
+  readonly smtpTlsScript: string;
+};
+interface SetHostsOptions {
+  /** Use an HTTPS connection to the server. */
+  useSsl?: boolean | null;
+  /** Path to the CA certificate chain (used when `useSsl` is set). */
+  sslCertPath?: string | null;
+  /** Skip certificate verification (used when `useSsl` is set). */
+  skipCertificateVerification?: boolean;
+  username?: string | null;
+  password?: string | null;
+  /**
+   * The Base64-encoded API key. Accepted as parsedmarc accepts it, but
+   * opensearch-py ignores a client-level `api_key`, so parsedmarc never
+   * sends it; neither does tsdmarc.
+   */
+  apiKey?: string | null;
+  /**
+   * Request timeout in seconds (default 60). `null` means no timeout; 0 or
+   * less raises `ValueError`, like opensearch-py.
+   */
+  timeout?: number | null;
+  /** `basic` (default) or `awssigv4`. */
+  authType?: string;
+  /** AWS region for SigV4 auth (required for `awssigv4`). */
+  awsRegion?: string | null;
+  /** AWS service for SigV4 signing (default `es`; `aoss` for Serverless). */
+  awsService?: string;
+}
+/**
+ * Creates an OpenSearch client the way {@link setHosts} does, without
+ * registering it as the default connection. Pass it as `client` to the save
+ * functions, createIndexes() and migrateIndexes() to write to several
+ * clusters from one process. Close it with `client.close()`.
+ */
+export declare function createClient(hosts: string | string[], options?: SetHostsOptions): Promise<Client>;
+/**
+ * Sets the OpenSearch hosts to use, and registers the client as the
+ * default connection the other functions use.
+ *
+ * A client registered by an earlier call is replaced but not closed, as in
+ * parsedmarc (the DSL's connection registry only drops it): its owner may
+ * still be using it or put it back (the CLI's configuration reload). Close
+ * clients you no longer need with `client.close()`; on shutdown,
+ * `await getDefaultConnection()?.close()` then `setDefaultConnection(null)`.
+ *
+ * @returns The registered client. Callers that need to close this exact
+ * client later should hold on to it.
+ */
+export declare function setHosts(hosts: string | string[], options?: SetHostsOptions): Promise<Client>;
+/**
+ * The client registered as the `default` connection, or `null`. With
+ * {@link setDefaultConnection}, lets a caller snapshot and restore the
+ * module state setHosts() writes (the CLI's configuration reload).
+ */
+export declare function getDefaultConnection(): Client | null;
+/** Register `client` as the `default` connection (`null` removes it). */
+export declare function setDefaultConnection(client: Client | null): void;
+/** Selects the cluster a function writes to. */
+interface ConnectionOptions {
+  /**
+   * The client to use instead of the default connection setHosts()
+   * registers, such as one from {@link createClient}. The default connection
+   * is module state, shared by every caller in the process: an application
+   * that writes to several clusters at once passes the client of each.
+   */
+  client?: Client | null;
+}
+/**
+ * Create OpenSearch indexes that don't exist yet.
+ *
+ * @param settings Index settings (default: 1 shard, 0 replicas).
+ * @param mappings Mappings for new indexes (default: none, as in parsedmarc).
+ * @param options The cluster to use (default: the default connection).
+ */
+export declare function createIndexes(names: string[], settings?: Record<string, unknown> | null, mappings?: IndexMapping | null, options?: ConnectionOptions): Promise<void>;
+/**
+ * Create OpenSearch data streams and their index templates.
+ *
+ * For each name, puts an index template named after the stream whose
+ * `index_patterns` is exactly that name (no wildcard, so it never applies to
+ * the date-suffixed indexes written without data streams), and then creates
+ * the data stream if it does not exist yet. The template is put again by
+ * every process that writes to the stream, so edits made to it directly do
+ * not last; an ISM policy attaches itself to the stream's backing indices
+ * through its own `ism_template` instead. Each name is set up once per
+ * client and template.
+ *
+ * @param settings Index settings for the stream's backing indices (default:
+ * 1 shard, 0 replicas, as in {@link createIndexes}).
+ * @param mappings Mappings for the backing indices, plus `@timestamp` as a
+ * date (default: only `@timestamp`, as in parsedmarc). The save functions
+ * pass the mappings they create dated indexes with.
+ * @param options The cluster to use (default: the default connection).
+ * @throws {OpenSearchError} when a concrete index or alias already holds one
+ * of the names, or the cluster returns an error. A name that fails is not
+ * remembered, so the next save retries it.
+ */
+export declare function createDataStreams(names: string[], settings?: Record<string, unknown> | null, mappings?: IndexMapping | null, options?: ConnectionOptions): Promise<void>;
+interface MigrateIndexesOptions extends ConnectionOptions {
+  /** Aggregate index names (backfilled as the `name*` pattern). */
+  aggregateIndexes?: string[] | null;
+  /** Failure index names (accepted for API compatibility; unused). */
+  failureIndexes?: string[] | null;
+  /** SMTP TLS index names (backfilled as the `name*` pattern). */
+  smtpTlsIndexes?: string[] | null;
+  /**
+   * Exact index names to check for the pre-5.0.0 `published_policy.fo`
+   * `long` mapping, as the caller's prefix/suffix configuration names them.
+   */
+  legacyFoIndexes?: string[] | null;
+}
+/**
+ * Runs index migrations and backfills.
+ *
+ * First, the legacy `published_policy.fo` migration for each name in
+ * `legacyFoIndexes`: an index that maps the field as `long` (parsedmarc
+ * before 5.0.0) is rebuilt as a `-v2` index with the text/keyword shape, its
+ * documents are reindexed into it, and the original is deleted.
+ *
+ * Second, it backfills `dkim_results_combined`/`spf_results_combined` on
+ * aggregate documents and `policies_combined`/`failure_details_combined` on
+ * SMTP TLS documents saved before those fields existed, as non-blocking
+ * `update_by_query` tasks against each `name*` pattern, guarded by a cheap
+ * `count`. Errors are logged as warnings, never thrown: the work is retried
+ * at the next startup.
+ */
+export declare function migrateIndexes(options?: MigrateIndexesOptions): Promise<void>;
+interface SaveOptions extends ConnectionOptions {
+  /** The suffix of the name of the index to save to. */
+  indexSuffix?: string | null;
+  /** The prefix of the name of the index to save to. */
+  indexPrefix?: string | null;
+  /**
+   * Use monthly indexes instead of daily indexes (ignored when
+   * `useDataStreams` is set).
+   */
+  monthlyIndexes?: boolean | null;
+  /** The number of shards to use in the index (default 1). */
+  numberOfShards?: number;
+  /** The number of replicas to use in the index (default 0). */
+  numberOfReplicas?: number;
+  /**
+   * Most indexes one aggregate report may spread over (default 31, 0 = no
+   * limit). The sender picks the dates, and each new index takes a shard from
+   * the cluster's limit; the records past this go to the report's first
+   * index, with their dates intact.
+   */
+  maxIndexesPerReport?: number;
+  /**
+   * Save to a data stream named like the index, without the date suffix,
+   * instead of to a dated index (see {@link createDataStreams}).
+   */
+  useDataStreams?: boolean;
+}
+/**
+ * Saves a parsed DMARC aggregate report to OpenSearch, one document per
+ * record.
+ *
+ * @throws {AlreadySaved} when the report is already in OpenSearch.
+ * @throws {OpenSearchError} when OpenSearch fails or rejects the document.
+ */
+export declare function saveAggregateReportToOpenSearch(aggregateReport: AggregateReport, options?: SaveOptions): Promise<void>;
+/**
+ * Saves a parsed DMARC failure report to OpenSearch.
+ *
+ * @throws {AlreadySaved} when the failure sample is already in OpenSearch.
+ * @throws {OpenSearchError} when OpenSearch fails or rejects the document.
+ * @throws {InvalidFailureReport} when the report lacks a required field.
+ */
+export declare function saveFailureReportToOpenSearch(failureReport: FailureReport, options?: SaveOptions): Promise<void>;
+/**
+ * Saves a parsed SMTP TLS report to OpenSearch.
+ *
+ * @throws {AlreadySaved} when the report is already in OpenSearch.
+ * @throws {OpenSearchError} when OpenSearch fails or rejects the document.
+ */
+export declare function saveSmtpTlsReportToOpenSearch(report: SMTPTLSReport, options?: SaveOptions): Promise<void>;
+/** Backward-compatible alias of {@link saveFailureReportToOpenSearch}. */
+export declare const saveForensicReportToOpenSearch: typeof saveFailureReportToOpenSearch;
+/** Raised when a scroll request fails on some shards (helpers.ScanError). */
+export declare class ScanError extends Error {
+  override name: string;
+  readonly scrollId: string;
+  constructor(scrollId: string, message: string);
+}
+/** Raised when some documents fail to index (helpers.BulkIndexError). */
+export declare class BulkIndexError extends Error {
+  override name: string;
+  readonly errors: unknown[];
+  constructor(message: string, errors: unknown[]);
+}
+export type { ConnectionOptions, DocumentMappings, MigrateIndexesOptions, SaveOptions, SetHostsOptions };
+//# sourceMappingURL=index.d.ts.map