@miguelmorales13/nestkit 0.5.1 → 0.7.0

package/dist/database/typeorm/index.js

@@ -0,0 +1,79 @@
+import {
+  __decorateClass
+} from "../../chunk-4MGIQFAJ.js";
+
+// src/database/typeorm/typeorm.module.ts
+import { Global, Module } from "@nestjs/common";
+import { DataSource } from "typeorm";
+var DATA_SOURCE = /* @__PURE__ */ Symbol("DATA_SOURCE");
+function buildDataSource(options) {
+  const url = options.url ?? process.env.DATABASE_URL;
+  const hasHost = Boolean(options.host);
+  if (!url && !hasHost) {
+    throw new Error("TypeOrmDbModule: DATABASE_URL is not set and no host was provided.");
+  }
+  return new DataSource({
+    type: "postgres",
+    url,
+    synchronize: false,
+    ...options
+  });
+}
+var TypeOrmDbModule = class {
+  static forRoot(options = {}) {
+    const provider = {
+      provide: DATA_SOURCE,
+      useFactory: async () => {
+        const dataSource = buildDataSource(options);
+        return dataSource.isInitialized ? dataSource : dataSource.initialize();
+      }
+    };
+    return { module: TypeOrmDbModule, providers: [provider], exports: [DATA_SOURCE] };
+  }
+  static forRootAsync(config) {
+    const provider = {
+      provide: DATA_SOURCE,
+      useFactory: async (...args) => {
+        const options = await config.useFactory(...args);
+        const dataSource = buildDataSource(options);
+        return dataSource.isInitialized ? dataSource : dataSource.initialize();
+      },
+      inject: config.inject ?? []
+    };
+    return {
+      module: TypeOrmDbModule,
+      imports: config.imports ?? [],
+      providers: [provider],
+      exports: [DATA_SOURCE]
+    };
+  }
+};
+TypeOrmDbModule = __decorateClass([
+  Global(),
+  Module({})
+], TypeOrmDbModule);
+
+// src/database/typeorm/tenant-scope.ts
+async function withTenantScope(dataSource, session, fn) {
+  const runner = dataSource.createQueryRunner();
+  await runner.connect();
+  await runner.startTransaction();
+  try {
+    for (const [name, value] of Object.entries(session)) {
+      await runner.query("SELECT set_config($1, $2, true)", [name, value]);
+    }
+    const result = await fn(runner.manager);
+    await runner.commitTransaction();
+    return result;
+  } catch (error) {
+    await runner.rollbackTransaction();
+    throw error;
+  } finally {
+    await runner.release();
+  }
+}
+export {
+  DATA_SOURCE,
+  TypeOrmDbModule,
+  withTenantScope
+};

package/dist/database/typeorm/tenant-scope.d.ts

@@ -0,0 +1,18 @@
+import type { DataSource, EntityManager } from 'typeorm';
+/**
+ * Runs `fn` inside a transaction whose Postgres session variables are set first,
+ * so Row-Level-Security policies keyed on those variables see the right tenant.
+ * This is the TypeORM equivalent of the `pg` `withTenantScope`: the ORM's own
+ * pool would otherwise run each query on an arbitrary connection with no session
+ * context, and RLS would see nothing (or the wrong rows).
+ *
+ * The `EntityManager` handed to `fn` is bound to that one connection and
+ * transaction — so `manager.getRepository(X).find()` inside runs scoped, and
+ * anything outside `fn` does NOT. Never leak the manager past the callback.
+ *
+ * `session` maps GUC name → value, e.g.
+ * `{ 'request.jwt.claim.sub': userId, 'request.jwt.claim.tenant': tenantId }`.
+ * Each is applied with `set_config(name, value, true)` (transaction-local), which
+ * is why the whole thing has to be one transaction on one connection.
+ */
+export declare function withTenantScope<T>(dataSource: DataSource, session: Record<string, string>, fn: (manager: EntityManager) => Promise<T>): Promise<T>;

package/dist/database/typeorm/typeorm.module.d.ts

@@ -0,0 +1,35 @@
+import { type DynamicModule } from '@nestjs/common';
+import { type DataSourceOptions } from 'typeorm';
+/** DI token for the shared TypeORM {@link DataSource}. Inject with `@Inject(DATA_SOURCE)`. */
+export declare const DATA_SOURCE: unique symbol;
+/**
+ * Options for the DataSource. Everything TypeORM's Postgres options accept, minus
+ * the bits this module fixes: `type` is always `postgres`, and `synchronize` is
+ * forced off (schema changes go through migrations, never an auto-sync that would
+ * happily drop a column in production). `url` defaults to `DATABASE_URL`.
+ */
+export type TypeOrmDbOptions = Partial<Omit<DataSourceOptions, 'type' | 'synchronize'>>;
+/**
+ * Provides a single, initialized TypeORM {@link DataSource} for the app, on
+ * Postgres (works with any Postgres, including Neon). Register once in the root
+ * module; inject the DataSource with `@Inject(DATA_SOURCE)`.
+ *
+ * For multi-tenant apps that rely on Postgres RLS, pair it with `withTenantScope`
+ * (same folder): the ORM pool alone has no per-request session, so tenant-scoped
+ * work must go through that helper.
+ *
+ * ```ts
+ * TypeOrmDbModule.forRoot({ entities: [User, Order], migrations: ['dist/migrations/*.js'] })
+ * ```
+ *
+ * `synchronize` is always off and `type` is always `postgres` — schema changes go
+ * through migrations. Install `typeorm` (optional peer dep) to use this module.
+ */
+export declare class TypeOrmDbModule {
+    static forRoot(options?: TypeOrmDbOptions): DynamicModule;
+    static forRootAsync(config: {
+        imports?: any[];
+        inject?: any[];
+        useFactory: (...args: any[]) => TypeOrmDbOptions | Promise<TypeOrmDbOptions>;
+    }): DynamicModule;
+}

package/dist/index.cjs

@@ -1,54 +1,54 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});require('./chunk-KVBQBT3D.cjs');
 
 
 
-var _chunkRF75KC63cjs = require('./chunk-RF75KC63.cjs');
 
+var _chunkSPTDXUEDcjs = require('./chunk-SPTDXUED.cjs');
 
 
 
-var _chunkSPTDXUEDcjs = require('./chunk-SPTDXUED.cjs');
 
+var _chunkRF75KC63cjs = require('./chunk-RF75KC63.cjs');
+require('./chunk-7SOM7EZP.cjs');
+require('./chunk-MR2IFCZE.cjs');
 
 
-var _chunkM3EL5O6Tcjs = require('./chunk-M3EL5O6T.cjs');
 
 
+var _chunkV2M75FN3cjs = require('./chunk-V2M75FN3.cjs');
 
 
-var _chunkV2M75FN3cjs = require('./chunk-V2M75FN3.cjs');
-require('./chunk-MR2IFCZE.cjs');
-require('./chunk-KVBQBT3D.cjs');
 
 
-var _chunk54ZXIB5Tcjs = require('./chunk-54ZXIB5T.cjs');
 
 
-var _chunkTJHRABMLcjs = require('./chunk-TJHRABML.cjs');
+var _chunkFDNGAYTZcjs = require('./chunk-FDNGAYTZ.cjs');
 
 
+var _chunkYARLPYG5cjs = require('./chunk-YARLPYG5.cjs');
 
-var _chunk3CLYZC3Tcjs = require('./chunk-3CLYZC3T.cjs');
 
+var _chunkJ7TURDALcjs = require('./chunk-J7TURDAL.cjs');
 
-var _chunkQS2W5XCQcjs = require('./chunk-QS2W5XCQ.cjs');
-require('./chunk-7SOM7EZP.cjs');
 
+var _chunkTJHRABMLcjs = require('./chunk-TJHRABML.cjs');
 
 
+var _chunkZA56XBCKcjs = require('./chunk-ZA56XBCK.cjs');
 
 
+var _chunkR7BVS6CIcjs = require('./chunk-R7BVS6CI.cjs');
 
-var _chunkFDNGAYTZcjs = require('./chunk-FDNGAYTZ.cjs');
 
 
-var _chunkJ7TURDALcjs = require('./chunk-J7TURDAL.cjs');
+var _chunk3CLYZC3Tcjs = require('./chunk-3CLYZC3T.cjs');
 
 
-var _chunkZA56XBCKcjs = require('./chunk-ZA56XBCK.cjs');
+var _chunkQS2W5XCQcjs = require('./chunk-QS2W5XCQ.cjs');
 
 
-var _chunkR7BVS6CIcjs = require('./chunk-R7BVS6CI.cjs');
+
+var _chunkM3EL5O6Tcjs = require('./chunk-M3EL5O6T.cjs');
 require('./chunk-2REOCMUD.cjs');
 
 
@@ -75,4 +75,4 @@ require('./chunk-2REOCMUD.cjs');
 
 
 
-exports.AppException = _chunkR7BVS6CIcjs.AppException; exports.BaseCrudService = _chunk3CLYZC3Tcjs.BaseCrudService; exports.BaseResponseDto = _chunkQS2W5XCQcjs.BaseResponseDto; exports.ConflictAppException = _chunkFDNGAYTZcjs.ConflictAppException; exports.ForbiddenAppException = _chunkFDNGAYTZcjs.ForbiddenAppException; exports.GlobalExceptionFilter = _chunkJ7TURDALcjs.GlobalExceptionFilter; exports.I18nModule = _chunkM3EL5O6Tcjs.I18nModule; exports.NotFoundAppException = _chunkFDNGAYTZcjs.NotFoundAppException; exports.PG_POOL = _chunkRF75KC63cjs.PG_POOL; exports.PgModule = _chunkRF75KC63cjs.PgModule; exports.REQUEST_ID_HEADER = _chunkV2M75FN3cjs.REQUEST_ID_HEADER; exports.RequestContext = _chunkZA56XBCKcjs.RequestContext; exports.RequestIdMiddleware = _chunkV2M75FN3cjs.RequestIdMiddleware; exports.ResponseInterceptor = _chunkTJHRABMLcjs.ResponseInterceptor; exports.SUPABASE_ANON_CLIENT = _chunkSPTDXUEDcjs.SUPABASE_ANON_CLIENT; exports.SUPABASE_SERVICE_ROLE_CLIENT = _chunkSPTDXUEDcjs.SUPABASE_SERVICE_ROLE_CLIENT; exports.SupabaseModule = _chunkSPTDXUEDcjs.SupabaseModule; exports.TrackingModule = _chunkV2M75FN3cjs.TrackingModule; exports.UnauthorizedAppException = _chunkFDNGAYTZcjs.UnauthorizedAppException; exports.ValidationAppException = _chunkFDNGAYTZcjs.ValidationAppException; exports.applyNestKitDefaults = _chunk54ZXIB5Tcjs.applyNestKitDefaults; exports.createCrudController = _chunk3CLYZC3Tcjs.createCrudController; exports.translateOr = _chunkM3EL5O6Tcjs.translateOr; exports.withTenantScope = _chunkRF75KC63cjs.withTenantScope;
+exports.AppException = _chunkR7BVS6CIcjs.AppException; exports.BaseCrudService = _chunk3CLYZC3Tcjs.BaseCrudService; exports.BaseResponseDto = _chunkQS2W5XCQcjs.BaseResponseDto; exports.ConflictAppException = _chunkFDNGAYTZcjs.ConflictAppException; exports.ForbiddenAppException = _chunkFDNGAYTZcjs.ForbiddenAppException; exports.GlobalExceptionFilter = _chunkJ7TURDALcjs.GlobalExceptionFilter; exports.I18nModule = _chunkM3EL5O6Tcjs.I18nModule; exports.NotFoundAppException = _chunkFDNGAYTZcjs.NotFoundAppException; exports.PG_POOL = _chunkRF75KC63cjs.PG_POOL; exports.PgModule = _chunkRF75KC63cjs.PgModule; exports.REQUEST_ID_HEADER = _chunkV2M75FN3cjs.REQUEST_ID_HEADER; exports.RequestContext = _chunkZA56XBCKcjs.RequestContext; exports.RequestIdMiddleware = _chunkV2M75FN3cjs.RequestIdMiddleware; exports.ResponseInterceptor = _chunkTJHRABMLcjs.ResponseInterceptor; exports.SUPABASE_ANON_CLIENT = _chunkSPTDXUEDcjs.SUPABASE_ANON_CLIENT; exports.SUPABASE_SERVICE_ROLE_CLIENT = _chunkSPTDXUEDcjs.SUPABASE_SERVICE_ROLE_CLIENT; exports.SupabaseModule = _chunkSPTDXUEDcjs.SupabaseModule; exports.TrackingModule = _chunkV2M75FN3cjs.TrackingModule; exports.UnauthorizedAppException = _chunkFDNGAYTZcjs.UnauthorizedAppException; exports.ValidationAppException = _chunkFDNGAYTZcjs.ValidationAppException; exports.applyNestKitDefaults = _chunkYARLPYG5cjs.applyNestKitDefaults; exports.createCrudController = _chunk3CLYZC3Tcjs.createCrudController; exports.translateOr = _chunkM3EL5O6Tcjs.translateOr; exports.withTenantScope = _chunkRF75KC63cjs.withTenantScope;

package/dist/index.js

@@ -1,38 +1,21 @@
-import {
-  PG_POOL,
-  PgModule,
-  withTenantScope
-} from "./chunk-VKOPDDCC.js";
+import "./chunk-EPVKCBPT.js";
 import {
   SUPABASE_ANON_CLIENT,
   SUPABASE_SERVICE_ROLE_CLIENT,
   SupabaseModule
 } from "./chunk-PA24P76K.js";
 import {
-  I18nModule,
-  translateOr
-} from "./chunk-IYUUYCP5.js";
+  PG_POOL,
+  PgModule,
+  withTenantScope
+} from "./chunk-VKOPDDCC.js";
+import "./chunk-DQYAIQQ5.js";
+import "./chunk-NAK4WDKS.js";
 import {
   REQUEST_ID_HEADER,
   RequestIdMiddleware,
   TrackingModule
 } from "./chunk-EYURGACO.js";
-import "./chunk-NAK4WDKS.js";
-import "./chunk-EPVKCBPT.js";
-import {
-  applyNestKitDefaults
-} from "./chunk-AOCF5QCZ.js";
-import {
-  ResponseInterceptor
-} from "./chunk-KDAA6GFF.js";
-import {
-  BaseCrudService,
-  createCrudController
-} from "./chunk-JOVBJDJ2.js";
-import {
-  BaseResponseDto
-} from "./chunk-XX2HPTRU.js";
-import "./chunk-DQYAIQQ5.js";
 import {
   ConflictAppException,
   ForbiddenAppException,
@@ -40,15 +23,32 @@ import {
   UnauthorizedAppException,
   ValidationAppException
 } from "./chunk-ORWJ7LES.js";
+import {
+  applyNestKitDefaults
+} from "./chunk-ANQ3YPDI.js";
 import {
   GlobalExceptionFilter
 } from "./chunk-7I2Y7V52.js";
+import {
+  ResponseInterceptor
+} from "./chunk-KDAA6GFF.js";
 import {
   RequestContext
 } from "./chunk-EBO6UKHL.js";
 import {
   AppException
 } from "./chunk-YFYHLYHN.js";
+import {
+  BaseCrudService,
+  createCrudController
+} from "./chunk-JOVBJDJ2.js";
+import {
+  BaseResponseDto
+} from "./chunk-XX2HPTRU.js";
+import {
+  I18nModule,
+  translateOr
+} from "./chunk-IYUUYCP5.js";
 import "./chunk-4MGIQFAJ.js";
 export {
   AppException,

package/dist/umami/index.cjs

@@ -0,0 +1,109 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
+
+
+var _chunk2REOCMUDcjs = require('../chunk-2REOCMUD.cjs');
+
+// src/umami/umami.module.ts
+var _common = require('@nestjs/common');
+
+// src/umami/umami.service.ts
+
+
+// src/umami/umami.options.ts
+var UMAMI_OPTIONS = /* @__PURE__ */ Symbol("UMAMI_OPTIONS");
+
+// src/umami/umami.service.ts
+var CLOUD = "https://api.umami.is/v1";
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var UmamiService = class {
+  constructor(options) {
+    this.options = options;
+    this.logger = new (0, _common.Logger)(UmamiService.name);
+  }
+  /** Whether there is enough configuration to make a call at all. */
+  get configured() {
+    return Boolean(this.options.apiKey && this.options.websiteId);
+  }
+  /** A range covering the last `days` days, ending now. */
+  static lastDays(days) {
+    const endAt = Date.now();
+    return { startAt: endAt - days * DAY_MS, endAt };
+  }
+  /** Visitors, pageviews, visits and bounces for a range. */
+  stats(range) {
+    return this.request("stats", range);
+  }
+  /**
+   * A breakdown by one dimension: top pages, referrers, countries, or —
+   * with `'event'` — how many times each custom event fired.
+   */
+  metrics(type, range, limit) {
+    return this.request("metrics", range, {
+      type,
+      ...limit ? { limit: String(limit) } : {}
+    });
+  }
+  /**
+   * How many times one named event fired. Returns 0 when the event exists but
+   * never fired, and `null` when the call itself failed — the difference
+   * matters: one is "nobody did it", the other is "we don't know".
+   */
+  async eventCount(name, range) {
+    const rows = await this.metrics("event", range);
+    if (rows === null) return null;
+    return _nullishCoalesce(_optionalChain([rows, 'access', _ => _.find, 'call', _2 => _2((row) => row.x === name), 'optionalAccess', _3 => _3.y]), () => ( 0));
+  }
+  async request(resource, range, extra = {}) {
+    if (!this.configured) {
+      this.logger.warn("Umami is not configured: apiKey and websiteId are required.");
+      return null;
+    }
+    const params = new URLSearchParams({
+      startAt: String(range.startAt),
+      endAt: String(range.endAt),
+      ...this.options.timezone ? { timezone: this.options.timezone } : {},
+      ...extra
+    });
+    const base = _nullishCoalesce(this.options.baseUrl, () => ( CLOUD));
+    try {
+      const response = await fetch(
+        `${base}/websites/${this.options.websiteId}/${resource}?${params}`,
+        { headers: { "x-umami-api-key": this.options.apiKey } }
+      );
+      if (!response.ok) {
+        this.logger.warn(`Umami ${resource}: HTTP ${response.status}`);
+        return null;
+      }
+      return await response.json();
+    } catch (error) {
+      this.logger.warn(`Umami ${resource}: ${error.message}`);
+      return null;
+    }
+  }
+};
+UmamiService = exports.UmamiService = _chunk2REOCMUDcjs.__decorateClass.call(void 0, [
+  _common.Injectable.call(void 0, ),
+  _chunk2REOCMUDcjs.__decorateParam.call(void 0, 0, _common.Inject.call(void 0, UMAMI_OPTIONS))
+], UmamiService);
+
+// src/umami/umami.module.ts
+var UmamiModule = class {
+  static forRoot(options) {
+    return {
+      module: UmamiModule,
+      providers: [
+        { provide: UMAMI_OPTIONS, useValue: options },
+        UmamiService
+      ],
+      exports: [UmamiService]
+    };
+  }
+};
+UmamiModule = exports.UmamiModule = _chunk2REOCMUDcjs.__decorateClass.call(void 0, [
+  _common.Module.call(void 0, {})
+], UmamiModule);
+
+
+
+
+exports.UMAMI_OPTIONS = UMAMI_OPTIONS; exports.UmamiModule = UmamiModule; exports.UmamiService = UmamiService;

package/dist/umami/index.d.ts

@@ -0,0 +1,4 @@
+export { UmamiModule } from './umami.module.js';
+export { UmamiService } from './umami.service.js';
+export { UMAMI_OPTIONS, type UmamiOptions } from './umami.options.js';
+export type { UmamiStats, UmamiMetric, UmamiMetricType, UmamiRange, } from './umami.types.js';

package/dist/umami/index.js

@@ -0,0 +1,109 @@
+import {
+  __decorateClass,
+  __decorateParam
+} from "../chunk-4MGIQFAJ.js";
+
+// src/umami/umami.module.ts
+import { Module } from "@nestjs/common";
+
+// src/umami/umami.service.ts
+import { Inject, Injectable, Logger } from "@nestjs/common";
+
+// src/umami/umami.options.ts
+var UMAMI_OPTIONS = /* @__PURE__ */ Symbol("UMAMI_OPTIONS");
+
+// src/umami/umami.service.ts
+var CLOUD = "https://api.umami.is/v1";
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var UmamiService = class {
+  constructor(options) {
+    this.options = options;
+    this.logger = new Logger(UmamiService.name);
+  }
+  /** Whether there is enough configuration to make a call at all. */
+  get configured() {
+    return Boolean(this.options.apiKey && this.options.websiteId);
+  }
+  /** A range covering the last `days` days, ending now. */
+  static lastDays(days) {
+    const endAt = Date.now();
+    return { startAt: endAt - days * DAY_MS, endAt };
+  }
+  /** Visitors, pageviews, visits and bounces for a range. */
+  stats(range) {
+    return this.request("stats", range);
+  }
+  /**
+   * A breakdown by one dimension: top pages, referrers, countries, or —
+   * with `'event'` — how many times each custom event fired.
+   */
+  metrics(type, range, limit) {
+    return this.request("metrics", range, {
+      type,
+      ...limit ? { limit: String(limit) } : {}
+    });
+  }
+  /**
+   * How many times one named event fired. Returns 0 when the event exists but
+   * never fired, and `null` when the call itself failed — the difference
+   * matters: one is "nobody did it", the other is "we don't know".
+   */
+  async eventCount(name, range) {
+    const rows = await this.metrics("event", range);
+    if (rows === null) return null;
+    return rows.find((row) => row.x === name)?.y ?? 0;
+  }
+  async request(resource, range, extra = {}) {
+    if (!this.configured) {
+      this.logger.warn("Umami is not configured: apiKey and websiteId are required.");
+      return null;
+    }
+    const params = new URLSearchParams({
+      startAt: String(range.startAt),
+      endAt: String(range.endAt),
+      ...this.options.timezone ? { timezone: this.options.timezone } : {},
+      ...extra
+    });
+    const base = this.options.baseUrl ?? CLOUD;
+    try {
+      const response = await fetch(
+        `${base}/websites/${this.options.websiteId}/${resource}?${params}`,
+        { headers: { "x-umami-api-key": this.options.apiKey } }
+      );
+      if (!response.ok) {
+        this.logger.warn(`Umami ${resource}: HTTP ${response.status}`);
+        return null;
+      }
+      return await response.json();
+    } catch (error) {
+      this.logger.warn(`Umami ${resource}: ${error.message}`);
+      return null;
+    }
+  }
+};
+UmamiService = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(UMAMI_OPTIONS))
+], UmamiService);
+
+// src/umami/umami.module.ts
+var UmamiModule = class {
+  static forRoot(options) {
+    return {
+      module: UmamiModule,
+      providers: [
+        { provide: UMAMI_OPTIONS, useValue: options },
+        UmamiService
+      ],
+      exports: [UmamiService]
+    };
+  }
+};
+UmamiModule = __decorateClass([
+  Module({})
+], UmamiModule);
+export {
+  UMAMI_OPTIONS,
+  UmamiModule,
+  UmamiService
+};

package/dist/umami/umami.module.d.ts

@@ -0,0 +1,6 @@
+import { type DynamicModule } from '@nestjs/common';
+import { type UmamiOptions } from './umami.options.js';
+/** Read-only access to the Umami analytics API. See `UmamiService`. */
+export declare class UmamiModule {
+    static forRoot(options: UmamiOptions): DynamicModule;
+}

package/dist/umami/umami.options.d.ts

@@ -0,0 +1,20 @@
+export declare const UMAMI_OPTIONS: unique symbol;
+export interface UmamiOptions {
+    /** API key from Umami Cloud (Settings → API Keys), or a self-hosted token. */
+    apiKey?: string;
+    /** The website's UUID, shown next to its name in the dashboard. */
+    websiteId?: string;
+    /**
+     * API base URL. Defaults to Umami Cloud.
+     *
+     * Self-hosted instances serve the same endpoints under `/api`, so pass
+     * `https://your-host/api` there.
+     */
+    baseUrl?: string;
+    /**
+     * Timezone for the queries, as an IANA name. Umami buckets by day in this
+     * zone, so leaving it unset silently reports UTC days — which for anything
+     * outside UTC means a "day" that starts in the middle of the afternoon.
+     */
+    timezone?: string;
+}

package/dist/umami/umami.service.d.ts

@@ -0,0 +1,40 @@
+import { type UmamiOptions } from './umami.options.js';
+import type { UmamiMetric, UmamiMetricType, UmamiRange, UmamiStats } from './umami.types.js';
+/**
+ * Read-only client for the Umami analytics API.
+ *
+ * Only reads. Events are sent by the browser script; a backend writing them
+ * would be reporting traffic that never happened.
+ *
+ * Every method returns `null` instead of throwing when a call fails. A summary
+ * usually asks for several things at once, and one endpoint being down should
+ * not take the rest of the report with it — the caller decides what a missing
+ * block means. Failures are logged, so a persistent one is still visible.
+ *
+ * Deliberately has no opinion about what the numbers mean. Which events form
+ * a funnel, what to call them and how to phrase a report are product
+ * decisions that differ per app; this only fetches.
+ */
+export declare class UmamiService {
+    private readonly options;
+    private readonly logger;
+    constructor(options: UmamiOptions);
+    /** Whether there is enough configuration to make a call at all. */
+    get configured(): boolean;
+    /** A range covering the last `days` days, ending now. */
+    static lastDays(days: number): UmamiRange;
+    /** Visitors, pageviews, visits and bounces for a range. */
+    stats(range: UmamiRange): Promise<UmamiStats | null>;
+    /**
+     * A breakdown by one dimension: top pages, referrers, countries, or —
+     * with `'event'` — how many times each custom event fired.
+     */
+    metrics(type: UmamiMetricType, range: UmamiRange, limit?: number): Promise<UmamiMetric[] | null>;
+    /**
+     * How many times one named event fired. Returns 0 when the event exists but
+     * never fired, and `null` when the call itself failed — the difference
+     * matters: one is "nobody did it", the other is "we don't know".
+     */
+    eventCount(name: string, range: UmamiRange): Promise<number | null>;
+    private request;
+}

package/dist/umami/umami.types.d.ts

@@ -0,0 +1,24 @@
+/** What `GET /websites/:id/stats` returns. */
+export interface UmamiStats {
+    pageviews: number;
+    visitors: number;
+    visits: number;
+    bounces: number;
+    totaltime: number;
+}
+/**
+ * A single metric row. Umami names these `x` and `y` across every metric type,
+ * so the meaning of `x` depends on what was asked for: a URL, a referrer, a
+ * country, an event name.
+ */
+export interface UmamiMetric {
+    x: string | null;
+    y: number;
+}
+/** What `type=` accepts on the metrics endpoint. */
+export type UmamiMetricType = 'url' | 'path' | 'entry' | 'exit' | 'referrer' | 'title' | 'query' | 'browser' | 'os' | 'device' | 'country' | 'region' | 'city' | 'language' | 'event';
+/** A window of time, as milliseconds since the epoch. */
+export interface UmamiRange {
+    startAt: number;
+    endAt: number;
+}