# Docs

> Guides and API references for the Friends Of Adonis packages: GraphQL, OpenAPI, Stripe billing, search, feature flags, actions and maintenance mode for AdonisJS.

- Magnify: Full-text search for your Lucid models with Algolia, Meilisearch or Typesense, kept in sync automatically
  - [Introduction](/docs/magnify): AdonisJS Magnify adds driver based full-text search to your Lucid models: a Searchable mixin keeps Algolia, Meilisearch and Typesense indexes in sync.
  - [Getting Started](/docs/magnify/getting-started): Add @foadonis/magnify to AdonisJS, compose the Searchable mixin into a Lucid model, then connect Meilisearch, Typesense or Algolia in config/magnify.ts.
  - Engines
    - [Engines](/docs/magnify/engines): Pick the search engine backing Magnify: Algolia, Meilisearch or Typesense, each with its own config/magnify.ts setup walkthrough.
    - [Algolia](/docs/magnify/engines/algolia): Connect Magnify to Algolia: install algoliasearch, set ALGOLIA_APP_ID and ALGOLIA_API_KEY, then register engines.algolia in config/magnify.ts.
    - [Meilisearch](/docs/magnify/engines/meilisearch): Run Magnify on Meilisearch: install the meilisearch client, register engines.meilisearch, and declare filterable and sortable indexSettings.
    - [Typesense](/docs/magnify/engines/typesense): Back your Magnify search with Typesense: install typesense, configure nodes and apiKey, then declare collectionSettings fields and queryBy.

  - **Guide**
  - [Searching](/docs/magnify/searching): Query Searchable models with search(), refine using where, whereIn and whereNotIn, sort with orderBy, and page results through paginate.
  - [Custom Search Engine](/docs/magnify/custom-search-engine): Build your own Magnify engine by extending MagnifyEngine with update, delete, search, map, paginate and flush, then register it in config/magnify.ts.

  - **References**
  - [Commands](/docs/magnify/commands): Reference for the Magnify Ace commands: magnify:import, magnify:flush and magnify:sync-index-settings for loading, clearing and configuring search indexes.
- Shopkeeper: Expressive, fluent Stripe billing for AdonisJS: subscriptions, checkout, invoices, and webhooks
  - [Introduction](/docs/shopkeeper): AdonisJS Shopkeeper gives Stripe billing a fluent, expressive API so you can add subscriptions, trials, one-off charges, and invoices in minutes.
  - [Getting Started](/docs/shopkeeper/getting-started): Take a first Stripe payment from AdonisJS: add @foadonis/shopkeeper, run its billing migrations, then compose the billable() mixin into your User model.

  - ** Payments **
  - [Accepting Payments](/docs/shopkeeper/accepting-payments): Redirect customers to Stripe Checkout from AdonisJS: product and subscription sessions, promotion codes, checkoutCharge, tax IDs, and guest checkouts.
  - [Single Charges](/docs/shopkeeper/single-charges): Charge outside of a subscription using charge(), the invoice builder, pay() and payWith() payment intents, and issue refunds by payment intent ID.
  - [Invoices & Receipts](/docs/shopkeeper/invoices-and-receipts): Retrieve a customer's invoices, create new ones with InvoiceBuilder, and preview upcoming charges or price swaps before a plan change in AdonisJS Shopkeeper.

  - ** Subscriptions **
  - [Managing Subscriptions](/docs/shopkeeper/managing-subscriptions): Check subscribed() status, swap plans, adjust quantities, cancel and resume, and manage multi-price Stripe subscriptions with AdonisJS Shopkeeper.
  - [Offering Trials](/docs/shopkeeper/offering-trials): Offer free trials in AdonisJS with trialDays() and trialUntil(), or a card-free generic trial via trialEndsAt, then end or extend them at any time.
  - [Metered Billing](/docs/shopkeeper/metered-billing): Bill by usage in AdonisJS: create meteredPrice() subscriptions, send Stripe Billing Meter events with reportUsage(), and read back usageRecords().

  - ** Configuration **
  - [Handling Webhooks](/docs/shopkeeper/handling-webhooks): Keep your database in sync with Stripe via registerRoutes() and registerWebhookListeners(), the shopkeeper:webhook Ace command, and idempotent webhookAudit().
  - [Managing Customers](/docs/shopkeeper/managing-customers): Create and sync Stripe customers from your AdonisJS models, adjust customer balances, manage tax IDs, and send users to the Stripe billing portal.
  - [Managing Payment Methods](/docs/shopkeeper/managing-payment-methods): Collect cards with createSetupIntent() and Stripe.js, then list, add, delete, and set the default payment method on any Shopkeeper billable model.
  - [Taxes](/docs/shopkeeper/taxes): Enable Stripe Tax with the calculateTaxes config flag, or define taxRates() and priceTaxRates() on your billable model, and check tax exemption status.

  - **Separator**
  - [Migrate to 1.0.0](/docs/shopkeeper/migration): Upgrade @foadonis/shopkeeper from 0.1.x to 1.0.0: factory mixins such as billable(), the new checkout and invoice builders, and Stripe SDK v20 changes.
- OpenAPI: Generate OpenAPI V3 documentation from your AdonisJS controllers and models using TypeScript decorators.
  - [Introduction](/docs/openapi): AdonisJS OpenAPI turns decorated controllers and models into an OpenAPI V3 specification, served through Scalar, Swagger UI or Rapidoc.
  - [Getting Started](/docs/openapi/getting-started): Decorate an AdonisJS controller and model with @foadonis/openapi, call registerRoutes(), then browse the generated specification on /api, /api.json or /api.yaml.

  - ** Guide **
  - [Defining Schemas](/docs/openapi/types-and-parameters): Turn TypeScript classes into OpenAPI schemas with @ApiProperty and @ApiPropertyOptional, plus primitives, arrays, enums, raw schemas and circular types.
  - [Defining Endpoints](/docs/openapi/operations): Describe endpoints with @ApiTags, @ApiHeader and @ApiResponse, and switch the media type on a body to document multipart file uploads in AdonisJS.
  - [Schema from Validators](/docs/openapi/validators): Pass a VineJS or Zod validator to @ApiSchema and it documents the params, query and body of the operation from the schema you already validate with.
  - [Using Transformers](/docs/openapi/transformers): Extend OpenAPISerializer and register TransformerTypeLoader to build response schemas from AdonisJS transformers, including collections and pagination.
  - [Typesafe Frontend](/docs/openapi/frontend): Feed the schema generated by AdonisJS OpenAPI to openapi-fetch or Hey API for fully typed frontend calls, with a comparison to help you pick one.

  - **References**
  - [Configuration](/docs/openapi/configuration): Reference for config/openapi.ts in @foadonis/openapi: the ui renderer, document info metadata, custom type loaders and extra controller registration.
  - [Decorators](/docs/openapi/decorators): Full decorator reference for @foadonis/openapi, from @ApiOperation and @ApiResponse through @ApiSecurity, @ApiExtraModels and @ApiHideProperty.

  - **Advanced**
  - [Generic Types](/docs/openapi/generic-types): Mixins let a single PaginatedResponse factory build reusable AdonisJS OpenAPI schemas, shown here wrapping Lucid paginator meta around any model.
  - [Mapped Types (Soon)](/docs/openapi/mapped-types): Mapped types will let you derive a schema by picking or omitting properties of an existing one. Documentation lands with the feature itself.
  - [Custom Type Loaders](/docs/openapi/custom-type-loaders): A TypeLoaderFn turns a constructor the generator does not know, such as Luxon DateTime, into a SchemaObject, or stores a component and returns a $ref.
- GraphQL: Build code-first GraphQL APIs in AdonisJS with decorators, Apollo or Yoga, auth and realtime subscriptions

  - **Guide**
  - [Introduction](/docs/graphql): @foadonis/graphql turns your Lucid models and resolver classes into a GraphQL schema, on top of TypeGraphQL, with Bouncer authorization and subscriptions
  - [Getting Started](/docs/graphql/getting-started): Bootstrap a code-first API with @foadonis/graphql: choose the Yoga or Apollo driver, then write a Recipe type, a resolver and a query in the playground.
  - Drivers: Choose between the Apollo Server and GraphQL Yoga drivers and configure them in config/graphql.ts
    - [Apollo Driver](/docs/graphql/drivers/apollo): Configure Apollo Server with drivers.apollo() in config/graphql.ts, toggle introspection and the playground, and register Apollo Server plugins
    - [Yoga Driver](/docs/graphql/drivers/yoga): Set up GraphQL Yoga through drivers.yoga(), enable file uploads with the AdonisJS bodyparser processManually list and a File scalar, and add Yoga plugins

  - **Concepts**
  - [Types and Fields](/docs/graphql/types-and-fields): Map TypeScript classes to GraphQL types with the @ObjectType and @Field decorators, covering nullable fields, arrays, custom scalars and enums
  - [Resolvers](/docs/graphql/resolvers): Define queries, mutations and field resolvers as class methods using @Resolver, @Query, @Mutation and @Arg, with AdonisJS dependency injection built in
  - [Authorization](/docs/graphql/authorization): Protect queries, mutations and object fields with @Authorized, AdonisJS Bouncer abilities and policies, and read the logged in user via @CurrentUser or @Ctx
  - [Middlewares](/docs/graphql/middlewares): Intercept GraphQL operations in AdonisJS with middleware classes and guards, added with @UseMiddleware on methods, resolvers and fields or registered globally
  - [Subscriptions](/docs/graphql/subscriptions): Push realtime updates from AdonisJS with the @Subscription decorator, native or Redis PubSub drivers, WebSocket transport and typed PubSubEvents

  - **References**
  - [Configuration](/docs/graphql/configuration): Reference for config/graphql.ts, from resolver autoloading with HMR and emitSchemaFile SDL output to schema generation options and a custom scalarsMap.
  - [Decorators](/docs/graphql/decorators): A reference table of the @foadonis/graphql decorators, from @ObjectType, @Field and @Resolver to @Arg, @Ctx, @Root, @Directive and @UseMiddleware

  - **Advanced**
  - [Custom Decorators](/docs/graphql/custom-decorators): Cut boilerplate by composing your own decorators: a FieldID wrapper, createMethodMiddlewareDecorator, and class level middleware decorators for resolvers
  - [Validation](/docs/graphql/validation): Validate GraphQL inputs and args with class-validator decorators and the validate config option, and note that VineJS is not supported out of the box yet
  - [Generic Types](https://typegraphql.com/docs/generic-types.html)
- Actions: One action class per use case, invoked as a route handler, an Ace command or an event listener, with the business logic living in handle
  - [Introduction](/docs/actions): AdonisJS Actions encapsulates business logic in single-purpose BaseAction classes you can reuse as HTTP controllers, Ace commands and event listeners
  - [Getting Started](/docs/actions/getting-started): Add @foadonis/actions to AdonisJS, scaffold a class with make:action, then run it through the static run method or bind it straight to a route handler.
  - [Reference](/docs/actions/reference): API reference for AdonisJS Actions: BaseAction, the AsController, AsCommand and AsListener interfaces, loader, ActionsRunner, make:action and indexActions
  - [Best Practices](/docs/actions/best-practices): Naming conventions, folder layout and composition patterns for actions, plus keeping business logic in handle and calling actions instead of emitting events

  - **Guides**
  - [Using Actions as Controllers](/docs/actions/as-controller): Implement AsController to turn an action into an AdonisJS route handler, validate the request from HttpContext and inject services through the container
  - [Using Actions as Commands](/docs/actions/as-command): The AsCommand interface registers an action as an Ace command: customize commandName and description, then use prompts and logger inside asCommand
  - [Using Actions as Listeners](/docs/actions/as-listener): Wire actions to AdonisJS events with the AsListener interface, register them through emitter.on and type payloads with a BaseEvent class
  - [Telemetry](/docs/actions/telemetry): Add ActionsInstrumentation to bin/otel.ts so @foadonis/actions emits an OpenTelemetry span per action execution through the @adonisjs/otel package
- Flick: Typed, driver-based feature flags for AdonisJS: variants, per-scope caching, Edge tags, and test fakes.
  - [Introduction](/docs/flick): AdonisJS Flick is a typed, driver-based feature flag system: define a feature class once, then resolve it per user, tenant, or request.
  - [Getting Started](/docs/flick/getting-started): Set up @foadonis/flick end to end: configure the memory driver, compose the HasFeatures mixin into a model, and resolve a flag with flick.for(user).

  - ** Guides **
  - [Defining Features](/docs/flick/defining-features): Feature classes extend BaseFeature and return booleans or variants from resolve, short-circuit with before(), and identify scopes via FeatureScopeable.
  - [Resolving Features](/docs/flick/resolving-features): Read flags through flick.for(scope) with isActive, value, values and match, then write or remove stored values with define, activate, deactivate and clear.
  - [Edge Templates](/docs/flick/edge): Gate markup in Edge templates with the @feature and @featureInactive tags, or read variant values through the flick global that AdonisJS Flick registers.
  - [Cache Drivers](/docs/flick/drivers): Cache resolved flag values per scope with the memory and Redis drivers, or implement FlickDriverContract to back AdonisJS Flick with your own store.
  - [Testing Features](/docs/flick/testing): Swap real resolution for flick.fake(), pin flags with override, and assert what your code checked using assertResolved and assertResolvedFor in Japa.
- Maintenance: Put your AdonisJS application in maintenance mode with simple Ace commands and bypass secrets

  - **Guide**
  - [Introduction](/docs/maintenance): AdonisJS Maintenance adds down and up Ace commands to take your app offline safely, with bypass secrets, custom Edge pages and distributed drivers
  - [Getting Started](/docs/maintenance/getting-started): Adding @foadonis/maintenance registers its provider for you, so node ace maintenance:down takes the app offline and maintenance:up brings it back live.
  - [Commands](/docs/maintenance/commands): Flags for the maintenance:down command in AdonisJS: --secret to bypass, --template for a custom Edge page, --redirect, plus --retry and --refresh
  - [Drivers](/docs/maintenance/drivers): Configure the file or cache driver in config/maintenance.ts to store maintenance state, or extend MaintenanceDriver to build your own custom driver
- Crypt: Public-key encryption for AdonisJS dotenv files, so secrets live in version control and only the private key stays out of the repository.

  - **Guide**
  - [Introduction](/docs/crypt): AdonisJS Crypt encrypts your .env values with a public key so dotenv files can be committed safely, then decrypts them at boot through @adonisjs/env.
  - [Getting Started](/docs/crypt/getting_started): Install @foadonis/crypt, generate a keypair with crypt:init, encrypt your first secret, and gitignore the .env.keys file holding your private key.
  - [Commands](/docs/crypt/commands): Every Crypt Ace command in one place: crypt:init to create a keypair, crypt:set and crypt:get to write or read encrypted values, all scoped with --env.