| title | Scenarios |
|---|---|
| description | Detailed guides for common Dart and Flutter AT Protocol integrations. |
Poptart is split into small packages, but most consumer work falls into a few common scenarios. These guides show which package to use, which session model fits the job, and where generated lexicon types help.
| Scenario | Start here |
|---|---|
| User-facing Flutter or Dart app sign-in | OAuth Sign-In |
| Trusted scripts, cron jobs, and internal tools | Scripts And App Passwords |
| DID document lookup, operation history, and PLC exports | DID PLC Lookups |
| Handles, DIDs, AT URIs, and NSIDs at input boundaries | Primitive Validation |
| Private services, new lexicons, and raw endpoints | Custom XRPC Calls |
Use OAuth when a human is signing into an app. OAuth gives the user a browser
flow, avoids collecting their password, and returns a DPoP-bound session that
can be passed to PoptartClient.fromOAuthSession.
Use an app password for scripts and trusted tools that you run yourself. It is
simple, works well with createSession, and does not require redirect handling.
Do not use account passwords in shipped apps.
Use anonymous clients when the endpoint is public. Profile lookups, many search queries, and some service metadata calls do not need a session.
Use the same PoptartClient for generated methods or descriptors from any
lexicon. Generated lexicon calls are the preferred path for stable known
lexicons: they give you typed parameters, inputs, and responses without making
you switch clients by namespace.
Use raw get and post calls when you are working with a private method, a new
lexicon that has not been generated yet, or a small exploratory script where a
typed descriptor would be premature.