@lastshotlabs/slingshot-assets

npm install @lastshotlabs/slingshot-assets

Functions

`Assets`

Provider-owned package contract for slingshot-assets.

Source: packages/slingshot-assets/src/public.ts

`AssetsHealthCap`

Capability for reading the aggregated assets health snapshot.

Consumers resolve via ctx.capabilities.require(AssetsHealthCap)() and receive an AssetsHealth reflecting storage adapter, S3 circuit breaker, and image cache state at call time.

Source: packages/slingshot-assets/src/public.ts

`AssetsOrphanedKeysCap`

Capability for the orphaned-storage recovery API.

Consumers resolve via ctx.capabilities.require(AssetsOrphanedKeysCap)(since?) and receive a snapshot of OrphanedKeyRecords the delete-cascade middleware has accumulated since startup (or since the optional cutoff). The list is bounded in memory; durable retention is the operator’s responsibility via onOrphanedKey.

Source: packages/slingshot-assets/src/public.ts

`AssetsRuntimeCap`

Capability handle for the assets plugin runtime.

Cross-package consumers resolve it through ctx.capabilities.require(AssetsRuntimeCap) to fetch the bundled assets adapter, storage adapter, and resolved config.

Source: packages/slingshot-assets/src/public.ts

`createAssetsPackage`

Create the assets package using the definePackage authoring path.

The Asset entity is mounted through the package’s entities: [...] declaration; its adapter is TTL-wrapped inside the entity module’s wiring.buildAdapter callback and captured into the package’s closure-owned ref so the storage-delete middleware and the published capabilities all use the same adapter instance per package.

function createAssetsPackage(rawConfig: AssetsPluginConfig, deps: AssetsPackageDeps = {},): SlingshotPackageDefinition

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

`createOrphanedKeyRegistry`

Build a bounded in-memory orphaned-key registry. Default cap is 1 000 entries — enough to surface bursts without unbounded memory growth.

function createOrphanedKeyRegistry(maxRecords = 1000): OrphanedKeyRegistry

Source: packages/slingshot-assets/src/middleware/deleteStorageFile.ts

`localStorage`

Create a StorageAdapter backed by the local filesystem.

The adapter wraps every filesystem operation (put/get/delete) in a circuit breaker. After circuitBreakerThreshold consecutive operation failures (each one already retried up to retryAttempts times with exponential backoff) the breaker opens for circuitBreakerCooldownMs and rejects subsequent calls with LocalCircuitOpenError (code: 'LOCAL_CIRCUIT_OPEN') until the cooldown elapses, then admits a single half-open probe.

function localStorage(config: LocalStorageConfig): LocalStorageAdapter

Source: packages/slingshot-assets/src/adapters/local.ts

`memoryStorage`

Create a StorageAdapter that stores files in-process in memory.

Suitable for development and tests only.

function memoryStorage(options: { /** * Circuit breaker — number of consecutive operation failures before the * breaker opens and short-circuits subsequent calls. Default: 5. */ readonly circuitBreakerThreshold?: number; /** * Circuit breaker — cooldown duration in ms before allowing a half-open * probe after the breaker opens. Default: 30 000 ms. */ readonly circuitBreakerCooldownMs?: number; /** * Circuit breaker — clock used for cooldown comparisons. Override in tests * for deterministic state machines. Default: `Date.now`. */ readonly now?: () => number; } = {},): MemoryStorageAdapter

Source: packages/slingshot-assets/src/adapters/memory.ts

`resolveStorageAdapter`

Resolve a storage adapter from a declarative reference (s3 / local / memory) or pass through an existing runtime adapter instance.

function resolveStorageAdapter(ref: StorageAdapter | StorageAdapterRef, options?: ResolveStorageAdapterOptions,): StorageAdapter

Source: packages/slingshot-assets/src/adapters/index.ts

`s3Storage`

Create a StorageAdapter backed by an S3-compatible object store.

AWS SDK modules are loaded lazily so apps that do not use S3 avoid the import cost.

Remarks: Circuit breaker — the adapter wraps every S3 call (put/get/delete and presign-get) in a circuit breaker. After circuitBreakerThreshold consecutive operation failures (each one already retried up to retryAttempts times) the breaker opens for circuitBreakerCooldownMs and rejects subsequent calls with S3CircuitOpenError (code: 'S3_CIRCUIT_OPEN') until the cooldown elapses, then admits a single half-open probe. This prevents a sustained S3 outage from amplifying load against a struggling provider.

Remarks: presignPut() is intentionally not breaker-gated: it is a local signing operation that does not touch S3 servers. presignGet() is gated because the current implementation routes through withRetry and could (in some SDK versions) trigger STS lookups.

function s3Storage(config: S3StorageConfig): S3StorageAdapter

Source: packages/slingshot-assets/src/adapters/s3.ts

Classes

`ImageTransformError`

Error thrown when a requested transform exceeds configured limits.

Source: packages/slingshot-assets/src/image/types.ts

`ImageTransformTimeoutError`

Error thrown when transformation exceeds the configured wall-clock budget.

Source: packages/slingshot-assets/src/image/types.ts

`LocalCircuitOpenError`

Structured error thrown when the local filesystem circuit breaker is open. Callers can pattern-match on code === 'LOCAL_CIRCUIT_OPEN' to fail fast without waiting for the underlying request retries.

Source: packages/slingshot-assets/src/adapters/local.ts

`MemoryCircuitOpenError`

Structured error thrown when the memory storage circuit breaker is open. Callers can pattern-match on code === 'MEMORY_CIRCUIT_OPEN' to fail fast.

Source: packages/slingshot-assets/src/adapters/memory.ts

`S3CircuitOpenError`

Structured error thrown when the S3 circuit breaker is open. Callers can pattern-match on code === 'S3_CIRCUIT_OPEN' to fail fast without waiting for the underlying request retries.

Source: packages/slingshot-assets/src/adapters/s3.ts

Interfaces

`Asset`

Asset entity record persisted by the assets plugin.

Source: packages/slingshot-assets/src/types.ts

`AssetAdapter`

Adapter contract for the Asset entity.

Source: packages/slingshot-assets/src/types.ts

`AssetBeforeUploadInput`

Context passed to a beforeUpload guard: the resolved uploader and the fully decoded file, BEFORE it is persisted. The hook may inspect bytes (e.g. for malware scanning) or enforce per-user quotas, and reject by throwing — ideally an HTTPException so the status/message reach the client.

Source: packages/slingshot-assets/src/types.ts

`AssetsHealth`

Aggregated health snapshot for the assets plugin.

Returned by the getHealth() method attached to the plugin instance. status is derived from the underlying signals:

'unhealthy' when the storage circuit breaker is open or storage is misconfigured.
'degraded' when the storage circuit breaker is half-open.
'healthy' otherwise.

Source: packages/slingshot-assets/src/types.ts

`AssetsHealthDetails`

Domain-specific details for the assets plugin health snapshot.

Source: packages/slingshot-assets/src/types.ts

`AssetsPackageDeps`

Optional non-JSON dependencies the assets package accepts at construction time.

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

`AssetsPluginConfig`

Configuration for createAssetsPackage().

Source: packages/slingshot-assets/src/types.ts

`AssetsPluginState`

Runtime state published by the plugin through the AssetsRuntimeCap contract capability. Cross-package consumers fetch via ctx.capabilities.require(AssetsRuntimeCap).

Source: packages/slingshot-assets/src/types.ts

`AwsStaticCredentials`

Static AWS credentials object. Use this only when credentials never change during the process lifetime. For long-running services prefer a AwsCredentialProvider so STS/EC2/ECS rotation is honored.

Source: packages/slingshot-assets/src/adapters/s3.ts

`CreateAssetInput`

Input accepted by AssetAdapter.create().

Source: packages/slingshot-assets/src/types.ts

`ImageConfig`

Image optimization configuration for GET /assets/assets/:id/image.

Source: packages/slingshot-assets/src/types.ts

`LocalCircuitBreakerHealth`

Snapshot of the local adapter circuit breaker state.

Source: packages/slingshot-assets/src/adapters/local.ts

`LocalStorageAdapter`

Local storage adapter augmented with circuit breaker observability.

The returned object satisfies StorageAdapter and exposes a stable getCircuitBreakerHealth() helper so callers (health endpoints, metrics) can surface breaker state without poking at internals.

Source: packages/slingshot-assets/src/adapters/local.ts

`LocalStorageConfig`

Configuration for the local filesystem storage adapter.

Source: packages/slingshot-assets/src/adapters/local.ts

`MemoryCircuitBreakerHealth`

Snapshot of the memory adapter circuit breaker state.

Source: packages/slingshot-assets/src/adapters/memory.ts

`MemoryStorageAdapter`

Memory storage adapter augmented with circuit breaker observability.

The returned object satisfies StorageAdapter and exposes a stable getCircuitBreakerHealth() helper so callers (health endpoints, metrics) can surface breaker state without poking at internals.

Source: packages/slingshot-assets/src/adapters/memory.ts

`OrphanedKeyRecord`

Record passed to AssetsPluginConfig.onOrphanedKey and surfaced via the listOrphanedKeys() recovery API.

Source: packages/slingshot-assets/src/types.ts

`OrphanedKeyRegistry`

Recovery API for orphaned-key reconciliation. Apps can fetch the in-memory orphan list to re-attempt manual cleanup or to expose a dashboard view.

The list is bounded — the oldest entries are evicted once maxRecords is exceeded — so this is not durable storage. Apps that need persistence MUST wire onOrphanedKey to push records onto an external queue.

Source: packages/slingshot-assets/src/middleware/deleteStorageFile.ts

`PresignedUrlConfig`

Presigned URL configuration for asset upload and download operations.

Source: packages/slingshot-assets/src/types.ts

`S3CircuitBreakerHealth`

Snapshot of the S3 adapter circuit breaker state.

Source: packages/slingshot-assets/src/adapters/s3.ts

`S3StorageAdapter`

S3 storage adapter augmented with circuit breaker observability.

The returned object satisfies StorageAdapter and exposes a stable getCircuitBreakerHealth() helper so callers (health endpoints, metrics) can surface breaker state without poking at internals.

Source: packages/slingshot-assets/src/adapters/s3.ts

`S3StorageConfig`

Configuration for the S3-compatible storage adapter.

Compatible with AWS S3, Cloudflare R2, MinIO, and any S3-compatible endpoint.

Source: packages/slingshot-assets/src/adapters/s3.ts

`StorageAdapterRef`

Reference to a built-in storage adapter resolved by name.

Use this shape in config-driven mode to resolve a built-in storage adapter without passing a runtime object instance.

Source: packages/slingshot-assets/src/types.ts

`UpdateAssetInput`

Input accepted by AssetAdapter.update().

Source: packages/slingshot-assets/src/types.ts

Types

`AssetBeforeUploadHook`

Pre-persist upload guard. Throw to reject the upload.

Source: packages/slingshot-assets/src/types.ts

`AwsCredentialProvider`

AWS credential provider — async function the SDK calls each time it needs fresh credentials. The SDK caches the result until expiration passes.

Plug this in when you load credentials from a secret manager or rotate them periodically. Without this (and without AwsStaticCredentials), the SDK uses its default credential chain (env, profile, EC2/ECS metadata, STS web identity) which already refreshes automatically.

Source: packages/slingshot-assets/src/adapters/s3.ts