atproto_core 2.2.0

Core library for clients and tools. This package is mainly used by https://atprotodart.com packages.

Release Note

2.2.0

• feat: added computeRecordCid, which returns the CID a PDS will assign to a record by canonically DAG-CBOR-encoding it and hashing to a CIDv1. This lets a caller reference a record before it is written — for example to chain reply references across records submitted in one com.atproto.repo.applyWrites batch.
• chore: widen at_primitives to ^1.2.0, multiformats to ^1.3.0, and xrpc to ^1.1.3.

2.1.0

• feat: added ServiceContext.onSessionUpdated, a broadcast stream that emits the refreshed Session each time an expired access token is renewed. session already reflected the new credentials, but nothing told the caller to read it back — and because refresh tokens are single-use, a caller that kept persisting the session it originally passed in stored a spent refresh token, so the next run restored a session that could no longer be refreshed. Mirrors OAuthSessionManager.onSessionUpdated for the legacy (app-password) path; it stays silent on OAuth-backed contexts. Concurrent requests that share one deduplicated refresh emit exactly one event.

2.0.1

• docs: rewrite the README to document the actual public API — Session/OAuthSession, JWT decoding (decodeJwt/Jwt), the pluggable retry engine (RetryStrategy, RetryConfig, RetryContext, RetryReason, RetryEvent, Jitter), BaseHttpService/ServiceContext, Blob/BlobRef, decodeCar, isValidAppPassword, and the xrpc/multiformats/cbor re-exports — and frame the package as the shared core layer atproto/bluesky build on.
• docs: replace the placeholder example/example.md with a runnable example/example.dart covering RetryConfig/custom RetryStrategy, JWT decoding, Blob serialization, and app-password validation.
• chore: bump xrpc to ^1.1.2, at_primitives to ^1.1.1, and atproto_oauth to ^0.5.1.

2.0.0

• feat!: OAuth requests are now driven by OAuthSessionManager; ServiceContext takes oAuthSessionManager instead of oAuthSession, enabling transparent OAuth token auto-refresh. OAuth tokens are never JWT-decoded. restoreOAuthSession/OauthSessionExtension removed (opaque tokens). Legacy password-auth Session is unaffected.
• fix: OAuth requests target the session's PDS even when the OAuthSessionManager restores its session lazily — previously every request defaulted to bsky.social, causing spurious 401s.
• fix: a caller-supplied Authorization header (e.g. a service-auth Bearer token) is preserved instead of being overwritten by the session/DPoP token, fixing service-auth flows such as video upload.
• fix: concurrent expired requests now share a single legacy-session refresh instead of issuing a refresh stampede.
• feat: stream() accepts a service override and a channelFactory, and honors the configured protocol; the use_dpop_nonce retry awaits the nonce write before retrying.
• fix: a failing user-supplied DPoP nonce-cache write on the request success path is now contained instead of escaping as an uncaught asynchronous error, so a storage failure in DPoPNonceCache.set can no longer crash the app.
• fix: the rate-limit retry wait now parses the HTTP-date form of Retry-After (previously only delta-seconds was honored; a date silently degraded to plain backoff and could retry too early).
• perf: ServiceContext.service caches the resolved PDS endpoint per access JWT instead of base64/JSON-decoding the access token on every request when the did document has no #atproto_pds service.
• feat: retries are now driven by a pluggable RetryStrategy (FutureOr<Duration?> nextDelay(RetryContext)). RetryContext exposes the attempt count, failure RetryReason, request kind (query vs procedure), NSID, status code, and the server-provided Retry-After. Implement RetryStrategy for full control over backoff and which failures retry; the default RetryConfig now implements it.
• fix: by default a procedure (POST) is no longer retried after an ambiguous failure the server may already have applied (a timeout after the request was sent, a 5xx, or an inconclusive connection reset), preventing duplicate writes. Queries (GET) and subscriptions still retry as before, and 429/pre-connection network failures still retry for procedures. Set RetryConfig(retryProcedureOnAmbiguousFailure: true) to restore the previous unconditional behavior.

1.3.0

• feat: automatic access-token refresh — Challenge now retries once after refreshing on a genuine 401, with a pre-emptive refresh when the token is within 30s of expiry (the use_dpop_nonce path is unchanged).
• fix: Challenge now retries 429 (respecting ratelimit-reset/Retry-After), SocketException, and ClientException, and preserves the XRPCResponse<T> type — previously only TimeoutException and 500 were retried and the type was erased.
• fix: car_decoder handles variable-length multihash CIDs and raises a typed CarException on truncated input; tag-42 CID links are normalized to {$link: <cid>} so downstream keeps type info, and the triple jsonEncode/jsonDecode round-trip is gone.
• fix: decodeCar now normalizes plain (non-tagged) CBOR byte strings to {$bytes: <base64>} (standard base64, RFC 4648 section 4, no padding) per the atproto data model, instead of returning raw Uint8List.
• fix: atprotoPdsEndpoint keeps an explicit port, falls back to the JWT aud when the did document has no #atproto_pds, and guards malformed did documents.
• fix: caller-supplied headers can no longer override Authorization/DPoP; dpop-nonce lookup is case-insensitive.
• fix: empty $unknown maps are stripped from the wire JSON.
• fix: unify on the validating NsidConverter; the non-validating NSIDConverter alias is deprecated.
• chore: bump xrpc to ^1.1.0, at_primitives to ^1.1.0, multiformats to ^1.1.0, and atproto_oauth to ^0.4.0.

1.2.2

• fix: redact accessJwt/refreshJwt in Session.toString() so credentials are not leaked through logs or crash reporters.
• fix: forward the headers argument in BaseHttpService.post (previously dropped).
• fix: retry jitter is now inclusive [min, max] and no longer throws a RangeError when maxInSeconds is 0.
• chore: bump atproto_oauth and multiformats.

1.2.1

• chore: bump atproto_oauth.

1.2.0

• fix: optional jwt scope and auth identity. (#2224)

1.1.0

• Add optional $service parameter to video service methods (getJobStatus, getUploadLimits, uploadVideo).
• Export nanoid and @Protected annotation from atproto_core/internals.dart.

1.0.7

• MIGRATION: Updated to use the consolidated at_primitives package for all primitive AT Protocol types.
• IMPROVEMENT: Simplified dependency management by adopting unified primitive types from at_primitives.

1.0.6

• fix: Drop universal_io for WASM compatibility.

1.0.5

• chore: fix WARNING: The annotation 'JsonSerializable.new' can only be used on classes..

1.0.4

• chore: optimized structures.

1.0.3

• chore: Removed outdated processes.

1.0.2

• Fix SDK constraint to '">=3.8.0 <4.0.0"'.

1.0.1

• chore: optimized docs.

1.0.0

• Jwt.aud is now nullable based on RFC 7519. (#1982)
• Bump SDK constraint to '^3.8.0'.

0.11.2

• Bump xrpc.

0.11.1

• Retry if a DPoP nonce error occurs during the execution of OAuthClient.refresh.
• Add restoreOAuthSession function.

0.11.0

• Expose atproto_oauth package.
• Add .oAuthSession parameter on ServiceContext.
• Rename AuthToken to Jwt.
  • Change type of scope from enum to String
  • Rename subject to sub
  • Rename expiresAt to exp
  • Rename issuedAt to iat
• Rename extended getters on Session
  • From accessToken to accessTokenJwt
  • From refreshToken to refreshTokenJwt

0.10.6

• Add service parameter on ServiceContext.get and ServiceContext.post. (#1783)

0.10.5

• Expose NsidConverter.
• Add client parameter for .get and .post on ServiceContext.

0.10.4

• Expose .atprotoPdsEndpoint from as an extension of Session. You can get specific pds endpoint based on did document.

0.10.3

• Change the type .collection property from String to NSID on AtUri. You need to do .collection.toString() when you want a string of collection. (#1551)

0.10.2

• The service is automatically resolved from the DID Document of the given Session. (#1543)
  • If no authentication is performed and no Session is passed, the default bsky.social is used.
  • If the user passes a specific service, it always respects the value of the user's service.
  • If something wrong happens for some reason, it uses bsky.social as default.

0.10.1

• Fixed a bug that prevented toJson on freezed objects.

0.10.0

• Add .active and .status properties on Session object. (#1516)
• Move BlobConverter, Blob, BlobRef from atproto package to atproto_core.

0.9.10

• Don't include Auth headers in .headers.

0.9.9

• Add appPassPrivileged on AuthScope. (#1501)
• Add .headers property. Returns the merged headers with global headers and auth header.

0.9.8

• Add authFactorToken parameter on createSession. (#1412)
• Add emailAuthFactor on Session. (#1412)

0.9.7

• Add global .headers on ServiceContext. (#1360)

0.9.6

• Upgrade at_uri. (#1300)

0.9.5

• Added .toUtcIso8601String on ServiceContext. (#1278)
• Bump SDK constraint to '^3.3.0'.

0.9.4

• Improved redundant error messages. Now it shows like GET https://bsky.social/xrpc/com.atproto.identity.resolveHandle 400 Error: Params must have the property "handle". (#1253)
• Exposed .service and .relayService properties on ServiceContext. (#1254)
• Added parameters arg and you can pass bytes to body arg on .post method. (#1252)
• BugFix: Made sure to check if the subscribeRepos blocks can be decoded. (#1239)

0.9.3

• Upgrade dependencies. (#1217)
• Added headers parameter for .get method on ServiceContext.

0.9.2

• Upgrade dependencies. (#1159)

0.9.1

• Upgrade dependencies. (#1146)

0.9.0

• Removed base_xrpc_service. (#1127)

0.8.1

• Upgraded xrpc.

0.8.0

• Upgraded NSID. (#1112)
• The following methods of BaseXRPCService now require an NSID argument. Immutable NSIDs are preferred. (#1114)
• Removed streamService and added relayService instead. Defaults to bsky.network. (#1116)

0.7.0

• Removed AuthType and ClientResolver. Let the server handle whether authentication is required or not. (#1102)

0.6.3

• Added cardyb.bsky.app as defaultLinkPreviewService. (#1009)

0.6.2

• Added AuthType.authOptional. (#1012)

0.6.1

• Added BaseHttpService.post. (#999)
• Fixed a bug that service names were not specified correctly when using stream endpoints.

0.6.0

• Added HTTP specific client. (#989)
• Renamed from UserContext to AuthType.

0.5.9

• Added .deleteSession function. (#963)
• Added didDoc field on Session object. (#968)

0.5.8

• Upgraded xrpc package.

0.5.7

• Added isEmailConfirmed field on Session. (#856)

0.5.6

• Upgraded xrpc package. Fixed field names for rate limit.

0.5.5

• Upgraded at_uri. (#797)

0.5.4

• Added .accessToken and .refreshToken properties on Session object. You can get decoded token objects based on JWT tokens. Also you can decode JWT token with decodeJwt function. (#787)

0.5.3

• Added Platform enum. (#709)
• Added isValidAppPassword function. (#713)

0.5.2

• Moved Session object and createSession function from atproto. And exposed refreshSession as a function. (#686)

0.5.1

• Upgraded multiformats.
• Upgrade cbor and now compatible with Flutter 3.13.0. (#681)

0.5.0

• Drop support for null unsafe Dart, bump SDK constraint to '^3.0.0'. (#599)
• Dart3 modifier applied.

0.4.6

• Upgraded xrpc and exposed RateLimit and RateLimitPolicy objects. (#636)
• Added Pagination object and paginate method in BaseService. (#626)

0.4.5

• Export useful ids and annotations as const. (#606)

0.4.4

• Export AtUriConverter() as const. (#605)

0.4.3

• Fixed parameter type of upload and subscribe in BaseService from NSID to String.

0.4.2

• Upgraded xrpc. (#563)

0.4.1

• Fixed to throw UnsupportedError when an anonymous user tries to access an endpoint that requires authentication. (#564)

0.4.0

• Added homepage in pubspec.yaml. (#549)
• Changed the argument of the upload method to byte data instead of a File object. This change allows uploads to be used without being affected by platform differences. (#556)

0.3.5

• Added adaptor parameter in get and subscribe, and removed decoder and converter. (#495)
• Added progress_status.dart.

0.3.4

• Improved generation of CID hash codes, allowing CID objects to be specified as keys for Maps, etc. (#490)

0.3.3

• Fixed subscribeRepoUpdates.

0.3.2

• Added decoder parameter in stream. (#472)

0.3.1

• Added converter parameter in stream<T>. (#446)

0.3.0

• Updated SDK to ">=2.17.0 <4.0.0". (#406)

0.2.10

• The retry algorithm has been modified to retry when an InternalServerError occurs as a result of XRPC communication. (#358)

0.2.9

• Upgraded xrpc and added stream method. (#318)

0.2.8

• Upgraded xrpc and added protocol option. (#269)

0.2.7

• Upgraded xrpc. (#249)

0.2.6

• Upgraded xrpc. (#249)

0.2.5

• Upgraded xrpc. (#249)

0.2.4

• Upgraded xrpc. (#249)

0.2.3

• Added upload feature. (#249)

0.2.2

• Upgraded xrpc to make this package compatible with Flutter. (#242)

0.2.1

• Fixed to body as optional and added headers for post. (#218)

0.2.0

• Use xrpc package and refactored structures. (#146)
• Exposed AtUri. (#144)

0.1.2

• Redefined retry processing as a class and exposed it as challenge.dart. (#128)

0.1.1

• Deleted ATProtoResponse<List> transformMultiDataResponse<D> from BaseService. (#112)

0.1.0

• Added core objects. (#70)
  • BaseService
  • Empty
  • ATProtoResponse
  • ATProtoRequest
  • ATProtoException
  • ForbiddenException

0.0.2

• Exposed client_context.dart.

0.0.1

• First Release!