@lastshotlabs/slingshot-admin

npm install @lastshotlabs/slingshot-admin

Functions

adminPluginConfigSchema

Configuration object for the Slingshot admin plugin.

All provider fields map directly to injectable provider interfaces. The plugin itself has no persistence of its own; storage is delegated to these providers.

Source: packages/slingshot-admin/src/types/config.ts

createAdminCircuitBreaker

Consecutive-failure circuit breaker for admin provider calls.

Guards outbound calls to external admin providers (Auth0, audit-log backends, etc.) so the plugin fails fast during sustained provider outages rather than letting request handlers thrash against a degraded upstream.

Mirrors the shape of slingshot-mail’s circuit breaker so operational behaviour stays uniform across production-track packages.

function createAdminCircuitBreaker(opts: AdminCircuitBreakerOptions): AdminCircuitBreaker

Source: packages/slingshot-admin/src/lib/circuitBreaker.ts

createAdminMetricsCollector

In-memory metrics collector for the admin plugin.

Tracks request counts, error counts, provider call statistics, and rate-limit hit counts. Data is retained until reset() is called (typically during teardown or between test runs).

This is a simple counter-based collector. For production observability, forward these metrics to your preferred aggregation pipeline (Prometheus, OpenTelemetry, etc.) by reading the snapshot at regular intervals.

function createAdminMetricsCollector(): AdminMetricsCollector

Source: packages/slingshot-admin/src/lib/metrics.ts

createAdminPlugin

Creates the Slingshot admin plugin, which mounts user-management, permissions, and (optionally) mail-preview routes under a configurable path.

All routes are protected by a single access-guard middleware that calls config.accessProvider.verifyRequest(). The resolved principal is stored on the Hono context as adminPrincipal for downstream handlers.

Circuit breaker: The access provider is wrapped in a circuit breaker (default: open after 5 consecutive failures, 30 s cooldown). When the breaker is open, admin requests return 503 immediately instead of timing out against a degraded upstream.

Health & metrics: GET <mountPath>/health and GET <mountPath>/metrics are mounted before the auth guard so monitoring systems can reach them.

Teardown: Calls teardown() to reset internal counters and state. Register this with your server’s shutdown handler.

function createAdminPlugin(rawConfig: AdminPluginConfig,): SlingshotPlugin &

Source: packages/slingshot-admin/src/plugin.ts

createAuth0AccessProvider

Configuration for the Auth0-backed AdminAccessProvider.

function createAuth0AccessProvider(config: Auth0AccessProviderConfig, deps: Auth0Deps = { createRemoteJWKSet, jwtVerify },): AdminAccessProvider

Source: packages/slingshot-admin/src/providers/auth0Access.ts

createConsoleAuditLogger

An audit event emitted by the admin plugin for CRUD operations.

Designed for admin-specific use — provides a higher-level view of who did what to which resource and whether it succeeded. The core AuditLogProvider interface used elsewhere in the plugin remains available for apps that need the full request-level event detail.

function createConsoleAuditLogger(baseLogger?: Logger): AdminAuditLogger

Source: packages/slingshot-admin/src/lib/auditLogger.ts

createMemoryAuditLogger

An audit event emitted by the admin plugin for CRUD operations.

Designed for admin-specific use — provides a higher-level view of who did what to which resource and whether it succeeded. The core AuditLogProvider interface used elsewhere in the plugin remains available for apps that need the full request-level event detail.

function createMemoryAuditLogger(): AdminAuditLogger &

Source: packages/slingshot-admin/src/lib/auditLogger.ts

createMemoryRateLimitStore

Pluggable rate-limit store interface and built-in implementations.

The admin plugin uses this to enforce destructive-mutation rate limits per principal+route+IP. The default in-process implementation does not survive a multi-instance deploy — production deploys should inject a Redis-backed implementation so all replicas share the same counter.

function createMemoryRateLimitStore(): AdminRateLimitStore

Source: packages/slingshot-admin/src/lib/rateLimitStore.ts

createRedisRateLimitStore

Pluggable rate-limit store interface and built-in implementations.

The admin plugin uses this to enforce destructive-mutation rate limits per principal+route+IP. The default in-process implementation does not survive a multi-instance deploy — production deploys should inject a Redis-backed implementation so all replicas share the same counter.

function createRedisRateLimitStore(opts: CreateRedisRateLimitStoreOptions,): AdminRateLimitStore

Source: packages/slingshot-admin/src/lib/rateLimitStore.ts

registerAdminResourceTypes

Registers all admin resource types and their role-to-action mappings into a PermissionRegistry.

Call this once during application bootstrap, before createApp(). Registries become immutable after the server starts.

Registered resource types:

• admin:user - read / write / suspend / delete
• admin:session - read / revoke
• admin:role - read / write
• admin:audit - read
• admin:permission - read / write
• admin:mail - read

Remarks: The super-admin role is not listed in any roles map. The permission registry handles super-admin specially: getActionsForRole(*, 'super-admin') always returns ['*'].

Remarks: Only resource types with implemented route handlers are registered here. Do not add resource types until the corresponding routes exist.

function registerAdminResourceTypes(registry: PermissionRegistry): void

Source: packages/slingshot-admin/src/lib/resourceTypes.ts

withRetry

Retry-with-backoff helper for transient provider failures.

Uses exponential backoff with full jitter so retries do not thash the upstream. Only retries errors that match the shouldRetry predicate (by default, all errors are retried up to maxRetries times).

async function withRetry<T>(fn: () => Promise<T>, opts: RetryOptions = {}): Promise<T>

Source: packages/slingshot-admin/src/lib/retry.ts

Classes

AdminAccessDeniedError

Errors thrown by the admin plugin.

Source: packages/slingshot-admin/src/errors.ts

AdminAuditLogError

Errors thrown by the admin plugin.

Source: packages/slingshot-admin/src/errors.ts

AdminCircuitOpenError

Consecutive-failure circuit breaker for admin provider calls.

Guards outbound calls to external admin providers (Auth0, audit-log backends, etc.) so the plugin fails fast during sustained provider outages rather than letting request handlers thrash against a degraded upstream.

Mirrors the shape of slingshot-mail’s circuit breaker so operational behaviour stays uniform across production-track packages.

Source: packages/slingshot-admin/src/lib/circuitBreaker.ts

AdminConfigError

Errors thrown by the admin plugin.

Source: packages/slingshot-admin/src/errors.ts

AdminRateLimitExceededError

Errors thrown by the admin plugin.

Source: packages/slingshot-admin/src/errors.ts

Interfaces

AdminAuditEvent

An audit event emitted by the admin plugin for CRUD operations.

Designed for admin-specific use — provides a higher-level view of who did what to which resource and whether it succeeded. The core AuditLogProvider interface used elsewhere in the plugin remains available for apps that need the full request-level event detail.

Source: packages/slingshot-admin/src/lib/auditLogger.ts

AdminAuditLogger

An audit event emitted by the admin plugin for CRUD operations.

Designed for admin-specific use — provides a higher-level view of who did what to which resource and whether it succeeded. The core AuditLogProvider interface used elsewhere in the plugin remains available for apps that need the full request-level event detail.

Source: packages/slingshot-admin/src/lib/auditLogger.ts

AdminCircuitBreaker

Consecutive-failure circuit breaker for admin provider calls.

Guards outbound calls to external admin providers (Auth0, audit-log backends, etc.) so the plugin fails fast during sustained provider outages rather than letting request handlers thrash against a degraded upstream.

Mirrors the shape of slingshot-mail’s circuit breaker so operational behaviour stays uniform across production-track packages.

Source: packages/slingshot-admin/src/lib/circuitBreaker.ts

AdminCircuitBreakerHealth

Consecutive-failure circuit breaker for admin provider calls.

Guards outbound calls to external admin providers (Auth0, audit-log backends, etc.) so the plugin fails fast during sustained provider outages rather than letting request handlers thrash against a degraded upstream.

Mirrors the shape of slingshot-mail’s circuit breaker so operational behaviour stays uniform across production-track packages.

Source: packages/slingshot-admin/src/lib/circuitBreaker.ts

AdminCircuitBreakerOptions

Consecutive-failure circuit breaker for admin provider calls.

Guards outbound calls to external admin providers (Auth0, audit-log backends, etc.) so the plugin fails fast during sustained provider outages rather than letting request handlers thrash against a degraded upstream.

Mirrors the shape of slingshot-mail’s circuit breaker so operational behaviour stays uniform across production-track packages.

Source: packages/slingshot-admin/src/lib/circuitBreaker.ts

AdminMetricsCollector

In-memory metrics collector for the admin plugin.

Tracks request counts, error counts, provider call statistics, and rate-limit hit counts. Data is retained until reset() is called (typically during teardown or between test runs).

This is a simple counter-based collector. For production observability, forward these metrics to your preferred aggregation pipeline (Prometheus, OpenTelemetry, etc.) by reading the snapshot at regular intervals.

Source: packages/slingshot-admin/src/lib/metrics.ts

AdminMetricsSnapshot

In-memory metrics collector for the admin plugin.

Tracks request counts, error counts, provider call statistics, and rate-limit hit counts. Data is retained until reset() is called (typically during teardown or between test runs).

This is a simple counter-based collector. For production observability, forward these metrics to your preferred aggregation pipeline (Prometheus, OpenTelemetry, etc.) by reading the snapshot at regular intervals.

Source: packages/slingshot-admin/src/lib/metrics.ts

AdminPluginConfig

Configuration object for the Slingshot admin plugin.

All provider fields map directly to injectable provider interfaces. The plugin itself has no persistence of its own; storage is delegated to these providers.

Source: packages/slingshot-admin/src/types/config.ts

AdminPluginHealth

Aggregated health snapshot for slingshot-admin.

slingshot-admin does not own a database or cache; this snapshot reflects configured providers and circuit breaker state without performing I/O.

Source: packages/slingshot-admin/src/types/health.ts

AdminRateLimitHitOptions

Pluggable rate-limit store interface and built-in implementations.

The admin plugin uses this to enforce destructive-mutation rate limits per principal+route+IP. The default in-process implementation does not survive a multi-instance deploy — production deploys should inject a Redis-backed implementation so all replicas share the same counter.

Source: packages/slingshot-admin/src/lib/rateLimitStore.ts

AdminRateLimitHitResult

Pluggable rate-limit store interface and built-in implementations.

The admin plugin uses this to enforce destructive-mutation rate limits per principal+route+IP. The default in-process implementation does not survive a multi-instance deploy — production deploys should inject a Redis-backed implementation so all replicas share the same counter.

Source: packages/slingshot-admin/src/lib/rateLimitStore.ts

AdminRateLimitStore

Pluggable rate-limit store interface and built-in implementations.

The admin plugin uses this to enforce destructive-mutation rate limits per principal+route+IP. The default in-process implementation does not survive a multi-instance deploy — production deploys should inject a Redis-backed implementation so all replicas share the same counter.

Source: packages/slingshot-admin/src/lib/rateLimitStore.ts

Auth0AccessProviderConfig

Configuration for the Auth0-backed AdminAccessProvider.

Source: packages/slingshot-admin/src/providers/auth0Access.ts

CreateRedisRateLimitStoreOptions

Pluggable rate-limit store interface and built-in implementations.

The admin plugin uses this to enforce destructive-mutation rate limits per principal+route+IP. The default in-process implementation does not survive a multi-instance deploy — production deploys should inject a Redis-backed implementation so all replicas share the same counter.

Source: packages/slingshot-admin/src/lib/rateLimitStore.ts

RedisRateLimitClientLike

Pluggable rate-limit store interface and built-in implementations.

The admin plugin uses this to enforce destructive-mutation rate limits per principal+route+IP. The default in-process implementation does not survive a multi-instance deploy — production deploys should inject a Redis-backed implementation so all replicas share the same counter.

Source: packages/slingshot-admin/src/lib/rateLimitStore.ts

RedisRateLimitMultiLike

Pluggable rate-limit store interface and built-in implementations.

The admin plugin uses this to enforce destructive-mutation rate limits per principal+route+IP. The default in-process implementation does not survive a multi-instance deploy — production deploys should inject a Redis-backed implementation so all replicas share the same counter.

Source: packages/slingshot-admin/src/lib/rateLimitStore.ts

RetryOptions

Retry-with-backoff helper for transient provider failures.

Uses exponential backoff with full jitter so retries do not thash the upstream. Only retries errors that match the shouldRetry predicate (by default, all errors are retried up to maxRetries times).

Source: packages/slingshot-admin/src/lib/retry.ts

Types

AdminEnv

Extra Hono context variables injected by the admin access-guard middleware. After the guard runs, c.get('adminPrincipal') is always a valid AdminPrincipal — the middleware rejects the request with 401 before reaching a route handler if the principal cannot be resolved.

Source: packages/slingshot-admin/src/types/env.ts

AdminVariables

Extra Hono context variables injected by the admin access-guard middleware. After the guard runs, c.get('adminPrincipal') is always a valid AdminPrincipal — the middleware rejects the request with 401 before reaching a route handler if the principal cannot be resolved.

Source: packages/slingshot-admin/src/types/env.ts