coffrify library
Official Dart/Flutter SDK for Coffrify — encrypted file transfer infrastructure (https://coffrify.com).
Quickstart
import 'package:coffrify/coffrify.dart';
final coffrify = Coffrify(
const CoffrifyConfiguration(apiKey: 'cof_live_…'),
);
final transfer = await coffrify.transfers.get('tr_…');
For Flutter widgets and secure-storage helpers, import
package:coffrify/flutter.dart. For test helpers, import
package:coffrify/testing.dart.
Classes
- AfterResponseContext
- Payload supplied to ClientHooks.afterResponse.
- AlertsResource
-
CRUD for
/v1/alerts. - AnalyticsResource
-
Workspace-level analytics (
/v1/analytics). - ApiKeyList
- List response for ApiKeysResource.list.
- ApiKeysResource
-
CRUD + rotation helpers for
/v1/api-keys. - ApiTokensResource
-
CRUD for
/v1/api-tokens. - AuditExportResult
- Result of AuditResource.export.
- AuditResource
-
Read + export helpers for
/v1/audit. - BeforeRequestContext
- Payload supplied to ClientHooks.beforeRequest.
- BillingResource
-
Subscription, usage and portal helpers under
/v1/billing/*. - BrandingResource
-
Read + patch the workspace branding payload (
/v1/branding). - ChangelogResource
-
Read endpoint for
/v1/changelog. - CircuitBreaker
- A client-side circuit breaker. Wrap every external call site that might fail and you'll degrade gracefully instead of melting the upstream during incidents.
- ClientHooks
- Hooks fired around each HTTP request, for audit/metrics/replays.
- CloneTransferResult
- Result of TransfersResource.clone.
- CoffresResource
-
CRUD + sections/items helpers for
/v1/coffres. - Coffrify
- Top-level Coffrify client. Build once at app startup, reuse across the app, and call close on shutdown.
- CoffrifyApiKey
- An API key minted by the workspace.
- CoffrifyAuditEntry
- One row from the workspace audit log.
- CoffrifyConfiguration
- Top-level configuration for Coffrify. Everything except apiKey has a sensible default.
- CoffrifyFile
- Metadata about a file attached to a transfer.
- CoffrifyHttpClient
- Low-level HTTP client. Resource classes are thin typed wrappers around request.
- CoffrifyLogger
- Structured logging surface.
- CoffrifyMeter
- Metrics surface — counters, histograms, gauges.
- CoffrifySpan
- Minimal span surface used by the SDK. Adapt to your tracing library.
- CoffrifyTracer
- Tracer factory.
- CoffrifyTransfer
- A Coffrify transfer.
- CoffrifyUploadUrl
-
One presigned URL ready to receive a file via
PUT. - CoffrifyWebhook
- A webhook subscription registered against the workspace.
- CollectionsResource
-
CRUD + item helpers for
/v1/collections. - CreateApiKeyOptions
- Options for ApiKeysResource.create.
- CreateApiKeyResult
- Result of ApiKeysResource.create. key is shown ONCE.
- CreateTransferOptions
- Strongly-typed options for TransfersResource.create.
- CreateTransferResult
-
Result of
transfers.create— the new transfer plus the presigned upload URLs callers mustPUTtheir bytes to. - CreateWebhookOptions
- Options for WebhooksResource.create.
- CreateWebhookResult
- Result of WebhooksResource.create.
- AWS-style decorrelated jitter — smoother distribution than vanilla exponential backoff for endpoints under sustained load.
- DomainsResource
-
CRUD + verification for
/v1/domains. - DownloadsResource
-
Read access to
/v1/transfers/:id/downloads. - ExponentialBackoff
-
Exponential backoff with jitter:
base * 2^attempt, capped at maxDelay. The default mirrors the JS SDK (exponentialBackoff). - FibonacciBackoff
-
Fibonacci backoff:
base * fib(attempt). Softer than exponential and friendly to bursty endpoints. - FixedDelay
- Fixed delay between attempts — useful for end-to-end tests where determinism beats jitter.
- FoldersResource
-
CRUD for
/v1/folders. - GdprExtraResource
- Companion resource to GdprResource for the secondary endpoints.
- GdprResource
- One-shot GDPR data export.
- IdempotencyStore
- Pluggable storage contract for idempotency caching.
- LeakyBucket
- Leaky bucket — paces requests to a steady drain rate. Pending acquisitions queue up; the queue is bounded by capacity to avoid unbounded memory growth.
- MagicLinksResource
-
CRUD for
/v1/magic-links(one-time access tokens). - MarketingResource
-
Newsletter, blog, docs/help search and pricing endpoints
(
/v1/marketing/*). - MembersResource
-
Read + invite helpers for
/v1/members. - MemoryIdempotencyStore
- In-memory store — process-local only. Suitable for tests, single- process apps, and Flutter UI flows where idempotency only needs to survive transient retries within a single run.
- MemoryReplayStore
- In-memory replay store. Bounded by maxEntries — when full, oldest entries are reaped lazily to reclaim space.
- MfaResource
-
Read endpoint for
/v1/mfa. - NoopTelemetry
- Drop-in adapter that discards every signal. Default when no telemetry is configured.
- NotificationsResource
-
Read + patch helpers for
/v1/notifications. - OnErrorContext
- Payload supplied to ClientHooks.onError.
- OnRetryContext
- Payload supplied to ClientHooks.onRetry.
-
Page<
T> - One page of items returned by a list endpoint.
- PaginateOptions
- Tuning knobs for paginate.
- PolicyInput
- Policy in the vocabulary of the public manifesto.
- ProgrammableResource
- High-level entry point that accepts the manifesto vocabulary and delegates to TransfersResource.create with the right snake_case mapping.
- QuotasResource
-
Read endpoints under
/v1/quotas/*. - RateLimiter
- Pluggable rate limiter contract.
- RateLimiterSnapshot
- Snapshot of the current limiter state. Useful for /healthz endpoints.
- RecipientsResource
-
CRUD for
/v1/recipients. - ReplayStore
- Pluggable storage contract for webhook replay detection.
- RequestOptions
-
Per-request overrides that resources can pass through to
request. - RequestsResource
-
CRUD + submission listing for
/v1/requests. - RetryContext
-
Context handed to RetryPolicy.next — the policy uses it to honour
Retry-Afterhints from the server or to specialise on transport error classes. - RetryDecision
- Outcome of a retry policy decision.
- RetryPolicy
- A pluggable strategy that decides whether and when to retry a failed request. Implementations must be cheap and synchronous.
- RoomsResource
-
CRUD for
/v1/rooms. - RotateApiKeyResult
- Result of ApiKeysResource.rotate.
- ScimResource
-
CRUD + audit log for SCIM tokens (
/v1/scim/*). - SessionsResource
-
User sessions surface (
/v1/sessions). - Input bundle for ProgrammableResource.share.
- SsoResource
-
Read + patch SAML SSO settings (
/v1/sso/config). - StatusResource
-
Read endpoints under
/v1/status/*. - TelemetryAdapter
- Bundles tracer / meter / logger for injection into the HTTP client.
- TemplatesResource
-
CRUD for
/v1/templates(reusable transfer policies). - TokenBucket
- Classic token bucket. Allows bursts up to capacity, refilled at refillPerSecond tokens per second.
- TransferFileInput
- File input for TransfersResource.create.
- TransferList
- One page of transfers.
- TransferQrCode
- Result of TransfersResource.qrcode.
- TransferRescanResult
- Result of TransfersResource.rescan.
- TransfersResource
-
CRUD + lifecycle helpers for
/v1/transfers. - Unlimited
- No-op limiter — appropriate for tests or local dev where rate management is delegated to the upstream.
- VerifyWebhookResult
- Outcome of verifyWebhook. Either event is set (verification succeeded) or failure is set.
- WebhookDeliveriesPage
- Page of webhook delivery attempts.
- WebhookDelivery
- One webhook delivery attempt.
- WebhookEvent
-
A decoded inbound webhook event. The
datafield is left as a rawMapbecause the shape depends on type; useWebhookEventCatalog.entryForto discover the documented payload. - WebhookEventCatalogEntry
- One entry in coffrifyEventCatalog.
- WebhookExtrasResource
-
Deep read endpoints under
/v1/webhooks/*. - WebhookReplayResult
- Result of WebhooksResource.replay.
- WebhookRetryPolicy
- Server-side retry tuning for a webhook subscription.
- WebhookRetryQueueResult
- Result of WebhooksResource.retry.
- WebhookRotateSecretResult
- Result of WebhooksResource.rotateSecret.
- WebhooksResource
-
CRUD + delivery helpers for
/v1/webhooks. - WebhookTestResult
- Result of WebhooksResource.test.
- WorkspaceExtrasResource
- Convenience wrappers for endpoints that don't fit a dedicated resource.
Enums
- CircuitState
- Lifecycle states for CircuitBreaker.
- CoffrifyEventType
- Every webhook event Coffrify can emit. The wire name is exposed via wire. Use CoffrifyEventType.fromWire when parsing inbound events.
- SpanStatusCode
- Span status codes mirrored from the OpenTelemetry spec.
- WebhookEventFamily
- Family a webhook event belongs to.
- WebhookEventRequiredPlan
- Minimum Coffrify plan required to receive a given event.
- WebhookEventStability
- Stability tier for a webhook event.
- WebhookVerifyFailure
- Result of verifyWebhook when verification fails.
Constants
-
coffrifyEventCatalog
→ const List<
WebhookEventCatalogEntry> - Static catalog of every Coffrify webhook event.
Functions
-
chunk<
T> (Stream< T> stream, int size) → Stream<List< T> > -
Chunk a stream into batches of
sizeitems. -
collect<
T> (Stream< T> stream) → Future<List< T> > - Collect a stream into a list. Use sparingly — defeats the purpose of lazy pagination for very large result sets.
-
deterministicKey(
String method, String path, [Object? body]) → String - Compute a deterministic, request-shape-stable idempotency key. Use this instead of a random UUID when the goal is "the same logical request must yield the same result" across crashes / restarts.
-
entryFor(
CoffrifyEventType type) → WebhookEventCatalogEntry? -
Lookup helper. Returns the catalog entry for
typewhen one exists. -
paginate<
T> ({required Future< Page< fetchPage({String? cursor, required int limit, required int offset}), PaginateOptions opts = const PaginateOptions()}) → Stream<T> >T> -
Build a lazy Stream from a "fetch one page" function. Works for
every
{ data: [], has_more, next_cursor }list endpoint in the Coffrify API. -
parseRetryAfter(
String? header) → Duration? -
Parse the
Retry-Afterheader into a Duration. Accepts both the seconds form (Retry-After: 30) and the HTTP-date form (Retry-After: Wed, 21 Oct 2026 07:28:00 GMT). -
verifyWebhook(
{required Object secret, required String body, required Map< String, String> headers, Duration tolerance = const Duration(minutes: 5)}) → Future<VerifyWebhookResult> -
Verify a webhook delivery using the Standard Webhooks v1 format
(preferred) with a fallback to the legacy
X-Coffrify-Signatureheader.
Exceptions / Errors
- CircuitOpenException
- Thrown when the client-side circuit breaker rejects a request without invoking the underlying transport. Carries the absolute timestamp at which the breaker will probe the upstream again.
- CoffrifyApiException
- Thrown for every non-2xx response returned by the Coffrify API as well as for network failures wrapped by the HTTP client.
- RateLimitOverflowException
- Thrown when a leaky-bucket rate limiter has no room left in its queue.