@drarzter/kafka-client 0.9.3 → 0.10.0

package/dist/client/outbox/outbox.types.d.ts

@@ -0,0 +1,144 @@
+import type { MessageHeaders, TopicMapConstraint } from "../types";
+import type { TransactionContext } from "../types/consumer.types";
+/**
+ * A single row from the application's transactional-outbox table.
+ *
+ * Application code inserts one of these into the outbox table inside the **same
+ * database transaction** as its business writes. The relay ({@link startOutboxRelay})
+ * later reads unpublished rows and publishes them to Kafka.
+ *
+ * @example
+ * ```ts
+ * // Inside a DB transaction, alongside your business INSERT/UPDATE:
+ * await tx.query(
+ *   `INSERT INTO outbox (id, topic, payload, key, correlation_id, event_id)
+ *    VALUES ($1, $2, $3, $4, $5, $6)`,
+ *   [randomUUID(), 'orders.created', JSON.stringify(order), order.id, corrId, eventId],
+ * );
+ * ```
+ */
+export interface OutboxMessage {
+    /**
+     * Unique row identifier. Used purely for idempotent marking — the relay passes
+     * these ids to {@link OutboxStore.markPublished} after Kafka acks the batch.
+     * This is **not** the Kafka `eventId` (use {@link OutboxMessage.eventId} for that).
+     */
+    id: string;
+    /** Destination Kafka topic. */
+    topic: string;
+    /** JSON-serialisable message body. Published as the Kafka message value. */
+    payload: unknown;
+    /** Optional Kafka partition key (guarantees per-key ordering). */
+    key?: string;
+    /** Optional custom Kafka headers merged with the auto-generated envelope headers. */
+    headers?: MessageHeaders;
+    /** Optional correlation id propagated to the Kafka `x-correlation-id` header. */
+    correlationId?: string;
+    /**
+     * Optional stable Kafka `x-event-id`. Persist this on the outbox row so that a
+     * re-published duplicate (see {@link startOutboxRelay} at-least-once semantics)
+     * carries the **same** event id, letting consumers deduplicate.
+     */
+    eventId?: string;
+}
+/**
+ * DB-agnostic contract the application implements to back the outbox relay.
+ *
+ * The library never touches your database directly — you own the schema and the
+ * queries. The relay only needs to (1) read unpublished rows oldest-first and
+ * (2) durably mark rows published once Kafka has acked them.
+ *
+ * A ready-made in-memory implementation ({@link InMemoryOutboxStore}) is provided
+ * for tests and as executable documentation.
+ *
+ * @example
+ * ```ts
+ * // Pseudo-Postgres store:
+ * const store: OutboxStore = {
+ *   async fetchUnpublished(limit) {
+ *     const { rows } = await pool.query(
+ *       `SELECT id, topic, payload, key, correlation_id AS "correlationId",
+ *               event_id AS "eventId", headers
+ *        FROM outbox
+ *        WHERE published_at IS NULL
+ *        ORDER BY created_at ASC
+ *        LIMIT $1`,
+ *       [limit],
+ *     );
+ *     return rows;
+ *   },
+ *   async markPublished(ids) {
+ *     await pool.query(
+ *       `UPDATE outbox SET published_at = now() WHERE id = ANY($1)`,
+ *       [ids],
+ *     );
+ *   },
+ * };
+ * ```
+ */
+export interface OutboxStore {
+    /**
+     * Fetch up to `limit` unpublished messages, **oldest first**.
+     *
+     * Must be safe to call concurrently with inserts from application code. The
+     * relay calls this once per poll tick; returning an empty array signals there
+     * is nothing to publish and the relay simply waits for the next tick.
+     */
+    fetchUnpublished(limit: number): Promise<OutboxMessage[]>;
+    /**
+     * Durably mark these ids as published. Called **only after** Kafka has acked
+     * the entire batch (i.e. the publishing transaction committed).
+     *
+     * This write should be durable and idempotent — a crash between the Kafka
+     * commit and this call causes the batch to be re-published on the next poll
+     * (at-least-once, see {@link startOutboxRelay}).
+     */
+    markPublished(ids: string[]): Promise<void>;
+}
+/**
+ * Tuning and observability options for {@link startOutboxRelay}.
+ *
+ * @example
+ * ```ts
+ * startOutboxRelay(kafka, store, {
+ *   pollIntervalMs: 500,
+ *   batchSize: 200,
+ *   onPublished: (n) => metrics.increment('outbox.published', n),
+ *   onError: (err, batch) =>
+ *     logger.error(`outbox batch of ${batch.length} failed`, err),
+ * });
+ * ```
+ */
+export interface OutboxRelayOptions {
+    /** Interval between poll ticks in ms. Default: `1000`. */
+    pollIntervalMs?: number;
+    /** Maximum rows fetched (and published in one transaction) per tick. Default: `100`. */
+    batchSize?: number;
+    /**
+     * Called when a poll iteration fails — either the publishing transaction
+     * threw or the store threw. The failed `batch` is **not** marked published and
+     * is retried on the next tick. The relay keeps running regardless.
+     *
+     * Default: log the error via the client logger.
+     */
+    onError?: (error: Error, batch: OutboxMessage[]) => void;
+    /** Called after a batch is successfully published and marked, with the batch size. */
+    onPublished?: (count: number) => void;
+}
+/**
+ * The narrowest producer surface the outbox relay needs: the ability to run an
+ * atomic Kafka transaction. Both `KafkaClient<T>` and the public
+ * `IKafkaProducer<T>` interface satisfy this.
+ */
+export interface OutboxProducer<T extends TopicMapConstraint<T>> {
+    transaction(fn: (ctx: TransactionContext<T>) => Promise<void>): Promise<void>;
+}
+/** Handle returned by {@link startOutboxRelay}. */
+export interface OutboxRelayHandle {
+    /**
+     * Stop the relay: halt the timer and wait for any in-flight iteration to
+     * finish before resolving. Idempotent.
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=outbox.types.d.ts.map

package/dist/client/outbox/outbox.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.types.d.ts","sourceRoot":"","sources":["../../../src/client/outbox/outbox.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;IACjB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1D;;;;;;;OAOG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,IAAI,CAAC;IACzD,sFAAsF;IACtF,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC;IAC7D,WAAW,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAED,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB"}

package/dist/client/security/acl.d.ts

@@ -0,0 +1,108 @@
+/**
+ * ACL requirement calculator for the topics, consumer groups, and
+ * transactional ids this library derives from your configuration.
+ *
+ * Features like retry topics, DLQ, delayed delivery, deduplication routing,
+ * DLQ replay, snapshots, and clock recovery all create extra topics
+ * (`<topic>.retry.N`, `<topic>.dlq`, `<topic>.delayed`, `<topic>.duplicates`)
+ * and consumer groups (`<groupId>-retry.N`, `<groupId>-delayed-relay`, plus
+ * timestamped ephemeral groups). On a locked-down cluster every one of them
+ * needs an ACL — `describeRequiredAcls()` enumerates them so nothing is
+ * discovered in production at 3 a.m.
+ */
+/** One ACL requirement on a Kafka resource. */
+export interface AclResource {
+    resourceType: "topic" | "group" | "transactional-id" | "cluster";
+    /**
+     * `literal` — exact name match. `prefixed` — Kafka prefixed ACL pattern;
+     * required for the timestamped ephemeral groups this library creates.
+     */
+    patternType: "literal" | "prefixed";
+    name: string;
+    /** Kafka operations: READ, WRITE, DESCRIBE, CREATE, DELETE. */
+    operations: string[];
+    /** Which feature requires this resource. */
+    reason: string;
+}
+/** Input describing how a service uses its `KafkaClient`. */
+export interface AclRequirementsInput {
+    clientId: string;
+    /** Default/typical consumer group ids used by this service. */
+    groupIds?: string[];
+    /** Topics this service produces to. */
+    produceTopics?: string[];
+    /** Topics this service consumes from. */
+    consumeTopics?: string[];
+    features?: {
+        /** `retryTopics: true` — adds `.retry.N` topics, `-retry.N` groups, and per-level tx ids. */
+        retryTopics?: {
+            maxRetries: number;
+        };
+        /** `dlq: true` — adds `.dlq` produce rights on consumed topics. */
+        dlq?: boolean;
+        /** `deliverAfterMs` / `startDelayedRelay` — adds `.delayed` topics, relay group, relay tx id. */
+        delayedDelivery?: boolean;
+        /** `deduplication.strategy: 'topic'` — adds `.duplicates` produce rights (or the custom topic). */
+        duplicatesTopic?: boolean | string;
+        /** `replayDlq()` usage — adds prefixed ephemeral replay groups + group deletion. */
+        dlqReplay?: boolean;
+        /** `readSnapshot` / `checkpointOffsets` / `restoreFromCheckpoint` — prefixed ephemeral groups. */
+        snapshots?: boolean;
+        /** `clockRecovery.topics` configured — prefixed ephemeral recovery groups. */
+        clockRecovery?: boolean;
+        /** `transaction()` usage — base transactional id. */
+        transactions?: boolean;
+        /** `autoCreateTopics: true` — cluster CREATE (avoid in production). */
+        autoCreateTopics?: boolean;
+    };
+}
+/**
+ * Enumerate every Kafka resource (with required operations) a service
+ * principal needs for the given usage profile — including all derived
+ * topics, companion groups, ephemeral groups, and transactional ids.
+ *
+ * @example
+ * ```ts
+ * const acls = describeRequiredAcls({
+ *   clientId: 'billing-svc',
+ *   groupIds: ['billing-svc-group'],
+ *   produceTopics: ['invoices.created'],
+ *   consumeTopics: ['orders.created'],
+ *   features: { retryTopics: { maxRetries: 3 }, dlq: true, dlqReplay: true },
+ * });
+ * console.log(toKafkaAclCommands(acls, 'User:billing-svc'));
+ * ```
+ */
+export declare function describeRequiredAcls(input: AclRequirementsInput): AclResource[];
+/**
+ * Render ACL requirements as `kafka-acls.sh` commands for a principal.
+ *
+ * @example
+ * ```ts
+ * toKafkaAclCommands(acls, 'User:billing-svc', 'broker:9092')
+ * // kafka-acls.sh --bootstrap-server broker:9092 --add --allow-principal User:billing-svc \
+ * //   --operation READ --operation DESCRIBE --topic orders.created
+ * ```
+ */
+export declare function toKafkaAclCommands(resources: AclResource[], principal: string, bootstrapServer?: string): string[];
+/** Cluster coordinates for building MSK resource ARNs. */
+export interface MskClusterCoordinates {
+    region: string;
+    accountId: string;
+    clusterName: string;
+    /** The UUID segment of the cluster ARN. */
+    clusterUuid: string;
+}
+/**
+ * Render ACL requirements as an AWS IAM policy document for MSK IAM auth.
+ *
+ * Prefixed patterns become `name*` wildcards in the resource ARN. The
+ * generated policy always includes `kafka-cluster:Connect` on the cluster.
+ * **Review before use** — validate against current AWS documentation and
+ * your organisation's least-privilege standards.
+ */
+export declare function toMskIamPolicy(resources: AclResource[], cluster: MskClusterCoordinates): {
+    Version: string;
+    Statement: unknown[];
+};
+//# sourceMappingURL=acl.d.ts.map

package/dist/client/security/acl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acl.d.ts","sourceRoot":"","sources":["../../../src/client/security/acl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,+CAA+C;AAC/C,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,OAAO,GAAG,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACjE;;;OAGG;IACH,WAAW,EAAE,SAAS,GAAG,UAAU,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,6DAA6D;AAC7D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,uCAAuC;IACvC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,yCAAyC;IACzC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE;QACT,6FAA6F;QAC7F,WAAW,CAAC,EAAE;YAAE,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC;QACrC,mEAAmE;QACnE,GAAG,CAAC,EAAE,OAAO,CAAC;QACd,iGAAiG;QACjG,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,mGAAmG;QACnG,eAAe,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;QACnC,oFAAoF;QACpF,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,kGAAkG;QAClG,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,8EAA8E;QAC9E,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,qDAAqD;QACrD,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,uEAAuE;QACvE,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC5B,CAAC;CACH;AAkBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,oBAAoB,GAC1B,WAAW,EAAE,CAgMf;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,WAAW,EAAE,EACxB,SAAS,EAAE,MAAM,EACjB,eAAe,SAAuB,GACrC,MAAM,EAAE,CAmBV;AAED,0DAA0D;AAC1D,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;CACrB;AAsBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,WAAW,EAAE,EACxB,OAAO,EAAE,qBAAqB,GAC7B;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,EAAE,CAAA;CAAE,CA4C3C"}

package/dist/client/security/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./security.types";
+export * from "./resolve-security";
+export * from "./providers";
+export * from "./acl";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/security/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/security/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,OAAO,CAAC"}

package/dist/client/security/providers.d.ts

@@ -0,0 +1,88 @@
+import type { OAuthBearerProvider } from "./security.types";
+/** Injectable dynamic-import function — overridable in tests. */
+type ImportFn = (specifier: string) => Promise<any>;
+/** Options for {@link awsMskIamProvider}. */
+export interface AwsMskIamProviderOptions {
+    /** AWS region of the MSK cluster, e.g. `"eu-west-1"`. */
+    region: string;
+    /**
+     * Optional AWS credentials profile / role logic is resolved by the signer
+     * library from the standard provider chain (env vars, ECS/EKS metadata,
+     * shared config). Nothing to configure here for IRSA / task roles.
+     */
+    /** @internal Injectable import for tests. */
+    importFn?: ImportFn;
+}
+/**
+ * OAUTHBEARER token provider for **AWS MSK IAM authentication**.
+ *
+ * Delegates token signing to the official `aws-msk-iam-sasl-signer-js`
+ * package (an optional dependency — install it alongside this library):
+ *
+ * ```bash
+ * npm install aws-msk-iam-sasl-signer-js
+ * ```
+ *
+ * Credentials are resolved from the standard AWS provider chain, so EKS
+ * IRSA, ECS task roles, and env credentials all work with no extra config.
+ * Authorisation is then governed by IAM policies (`kafka-cluster:*` actions) —
+ * see `describeRequiredAcls()` + `toMskIamPolicy()` to generate one covering
+ * every topic/group this library derives.
+ *
+ * @example
+ * ```ts
+ * const kafka = new KafkaClient(id, group, brokers, {
+ *   security: {
+ *     sasl: {
+ *       mechanism: 'oauthbearer',
+ *       oauthBearerProvider: awsMskIamProvider({ region: 'eu-west-1' }),
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function awsMskIamProvider(options: AwsMskIamProviderOptions): OAuthBearerProvider;
+/** Options for {@link gcpAccessTokenProvider}. */
+export interface GcpTokenProviderOptions {
+    /** OAuth scopes. Default: `["https://www.googleapis.com/auth/cloud-platform"]`. */
+    scopes?: string[];
+    /** Principal reported to the broker. Default: `"gcp"`. */
+    principal?: string;
+    /**
+     * Token validity reported to the driver (refresh margin), epoch-relative ms.
+     * GCP access tokens live ~1 h; default refresh window is 50 minutes.
+     */
+    tokenTtlMs?: number;
+    /** @internal Injectable import for tests. */
+    importFn?: ImportFn;
+}
+/**
+ * OAUTHBEARER token provider for **Google Cloud Managed Service for Apache
+ * Kafka** (and any broker accepting Google OAuth access tokens).
+ *
+ * Delegates to the official `google-auth-library` (optional dependency):
+ *
+ * ```bash
+ * npm install google-auth-library
+ * ```
+ *
+ * Uses Application Default Credentials, so GKE Workload Identity, attached
+ * service accounts, and `GOOGLE_APPLICATION_CREDENTIALS` all work unchanged.
+ * Verify the exact token format expected by your cluster against current
+ * Google documentation — this provider supplies a raw ADC access token.
+ *
+ * @example
+ * ```ts
+ * const kafka = new KafkaClient(id, group, brokers, {
+ *   security: {
+ *     sasl: {
+ *       mechanism: 'oauthbearer',
+ *       oauthBearerProvider: gcpAccessTokenProvider(),
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function gcpAccessTokenProvider(options?: GcpTokenProviderOptions): OAuthBearerProvider;
+export {};
+//# sourceMappingURL=providers.d.ts.map

package/dist/client/security/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../../src/client/security/providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAoB,MAAM,kBAAkB,CAAC;AAE9E,iEAAiE;AACjE,KAAK,QAAQ,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAIpD,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,mBAAmB,CAsBrB;AAED,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACtC,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,uBAA4B,GACpC,mBAAmB,CA6BrB"}

package/dist/client/security/resolve-security.d.ts

@@ -0,0 +1,19 @@
+import type { KafkaLogger } from "../types";
+import type { KafkaSecurityOptions } from "./security.types";
+/**
+ * Apply the secure-by-default rules to a user-supplied security config:
+ *
+ * 1. `sasl` present + `ssl` unset → `ssl: true`. Credentials never travel
+ *    over plaintext by accident; opting out requires an explicit `ssl: false`
+ *    (which logs a warning).
+ * 2. No `ssl`/`sasl` at all while any broker is non-local → one warning per
+ *    client, silenceable via `allowInsecure: true`.
+ *
+ * Never throws and never blocks a connection — the defaults protect, the
+ * user stays in control.
+ *
+ * @returns The effective options passed to the transport (may be `undefined`
+ *          when no security was configured).
+ */
+export declare function resolveSecurityOptions(security: KafkaSecurityOptions | undefined, brokers: string[], logger: KafkaLogger): KafkaSecurityOptions | undefined;
+//# sourceMappingURL=resolve-security.d.ts.map

package/dist/client/security/resolve-security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-security.d.ts","sourceRoot":"","sources":["../../../src/client/security/resolve-security.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAe7D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,OAAO,EAAE,MAAM,EAAE,EACjB,MAAM,EAAE,WAAW,GAClB,oBAAoB,GAAG,SAAS,CA0BlC"}

package/dist/client/security/security.types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * OAuth bearer token returned by an {@link OAuthBearerProvider}.
+ * Mirrors the shape expected by librdkafka's OAUTHBEARER mechanism.
+ */
+export interface OAuthBearerToken {
+    /** The raw token value presented to the broker. */
+    value: string;
+    /** Kafka principal name associated with the token. Default: `"kafka-client"`. */
+    principal?: string;
+    /**
+     * Absolute token expiry as epoch milliseconds. The driver refreshes the
+     * token before this deadline. Default: now + 15 minutes.
+     */
+    lifetimeMs?: number;
+    /** Optional SASL extensions forwarded to the broker. */
+    extensions?: Record<string, string>;
+}
+/**
+ * Async factory that produces a fresh OAuth bearer token.
+ * Called by the driver on connect and before each token expiry.
+ */
+export type OAuthBearerProvider = () => Promise<OAuthBearerToken>;
+/** SASL configuration — username/password mechanisms or OAUTHBEARER. */
+export type KafkaSaslOptions = {
+    mechanism: "plain" | "scram-sha-256" | "scram-sha-512";
+    username: string;
+    password: string;
+} | {
+    mechanism: "oauthbearer";
+    oauthBearerProvider: OAuthBearerProvider;
+};
+/**
+ * Transport security configuration for `KafkaClientOptions.security`.
+ *
+ * Secure-by-default behaviour (see `resolveSecurityOptions`):
+ * - When `sasl` is set and `ssl` is not, TLS is enabled automatically —
+ *   credentials never travel over plaintext unless you explicitly opt out
+ *   with `ssl: false` (which logs a warning).
+ * - Connecting to non-local brokers with no security at all logs a one-time
+ *   warning. Set `allowInsecure: true` to acknowledge and silence it
+ *   (e.g. a trusted private network or an mTLS-terminating service mesh).
+ *
+ * @example SASL/SCRAM over TLS (ssl auto-enabled)
+ * ```ts
+ * const kafka = new KafkaClient(id, group, brokers, {
+ *   security: {
+ *     sasl: { mechanism: 'scram-sha-512', username: 'svc', password: process.env.KAFKA_PASSWORD! },
+ *   },
+ * });
+ * ```
+ *
+ * @example AWS MSK IAM
+ * ```ts
+ * import { awsMskIamProvider } from '@drarzter/kafka-client/core';
+ *
+ * const kafka = new KafkaClient(id, group, brokers, {
+ *   security: {
+ *     sasl: { mechanism: 'oauthbearer', oauthBearerProvider: awsMskIamProvider({ region: 'eu-west-1' }) },
+ *   },
+ * });
+ * ```
+ */
+export interface KafkaSecurityOptions {
+    /**
+     * Enable TLS. Defaults to `true` when `sasl` is configured, otherwise `false`.
+     */
+    ssl?: boolean;
+    /** SASL authentication. */
+    sasl?: KafkaSaslOptions;
+    /**
+     * Acknowledge an intentionally insecure setup (plaintext to non-local
+     * brokers) and silence the warning. Has no effect when `ssl`/`sasl` are set.
+     */
+    allowInsecure?: boolean;
+}
+//# sourceMappingURL=security.types.d.ts.map

package/dist/client/security/security.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.types.d.ts","sourceRoot":"","sources":["../../../src/client/security/security.types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAElE,wEAAwE;AACxE,MAAM,MAAM,gBAAgB,GACxB;IACE,SAAS,EAAE,OAAO,GAAG,eAAe,GAAG,eAAe,CAAC;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,GACD;IACE,SAAS,EAAE,aAAa,CAAC;IACzB,mBAAmB,EAAE,mBAAmB,CAAC;CAC1C,CAAC;AAEN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,2BAA2B;IAC3B,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB"}

package/dist/client/transport/confluent.transport.d.ts

@@ -0,0 +1,32 @@
+import { KafkaJS } from "@confluentinc/kafka-javascript";
+import type { KafkaTransport, IProducer, IConsumer, IAdmin, IProducerCreationOptions, IConsumerCreationOptions, ITopicPartition, ITopicPartitions, ITopicPartitionOffset, IConsumerRunConfig } from "./transport.interface";
+export declare class ConfluentConsumer implements IConsumer {
+    private readonly consumer;
+    constructor(consumer: KafkaJS.Consumer);
+    /** Returns the underlying KafkaJS.Consumer — used by ConfluentTransaction.sendOffsets. */
+    getNative(): KafkaJS.Consumer;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    subscribe(options: {
+        topics: (string | RegExp)[];
+    }): Promise<void>;
+    run(config: IConsumerRunConfig): Promise<void>;
+    pause(assignments: ITopicPartitions[]): void;
+    resume(assignments: ITopicPartitions[]): void;
+    seek(options: ITopicPartitionOffset): void;
+    assignment(): ITopicPartition[];
+    commitOffsets(offsets: ITopicPartitionOffset[]): Promise<void>;
+    stop(): Promise<void>;
+}
+/**
+ * `KafkaTransport` implementation backed by `@confluentinc/kafka-javascript`.
+ * Wraps the KafkaJS-compatibility layer from librdkafka.
+ */
+export declare class ConfluentTransport implements KafkaTransport {
+    private readonly kafka;
+    constructor(clientId: string, brokers: string[], security?: import("../security/security.types").KafkaSecurityOptions);
+    producer(options?: IProducerCreationOptions): IProducer;
+    consumer(options: IConsumerCreationOptions): IConsumer;
+    admin(): IAdmin;
+}
+//# sourceMappingURL=confluent.transport.d.ts.map

package/dist/client/transport/confluent.transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confluent.transport.d.ts","sourceRoot":"","sources":["../../../src/client/transport/confluent.transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAGzD,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,SAAS,EACT,MAAM,EAGN,wBAAwB,EACxB,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAMnB,MAAM,uBAAuB,CAAC;AAuE/B,qBAAa,iBAAkB,YAAW,SAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,OAAO,CAAC,QAAQ;IAEvD,0FAA0F;IAC1F,SAAS,IAAI,OAAO,CAAC,QAAQ;IAIvB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,SAAS,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlE,GAAG,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,KAAK,CAAC,WAAW,EAAE,gBAAgB,EAAE,GAAG,IAAI;IAI5C,MAAM,CAAC,WAAW,EAAE,gBAAgB,EAAE,GAAG,IAAI;IAI7C,IAAI,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAI1C,UAAU,IAAI,eAAe,EAAE;IAIzB,aAAa,CAAC,OAAO,EAAE,qBAAqB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B;AA0ED;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;gBAGpC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,CAAC,EAAE,OAAO,4BAA4B,EAAE,oBAAoB;IA0BtE,QAAQ,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,SAAS;IAgBvD,QAAQ,CAAC,OAAO,EAAE,wBAAwB,GAAG,SAAS;IAsCtD,KAAK,IAAI,MAAM;CAGhB"}