saleor-app-sdk-REDIS_APL/docs/apl.md

APL - Auth Persistence Layer

APL is an interface for managing auth data of registered Apps. Implementing it does not restrict you from choosing the right technology for your project (for example Redis, Postgres, S3, etc.), and provides a common set of operations which can be used by your application and functions provided by App SDK.

Available methods

• get: (domain: string) => Promise<AuthData | undefined> - If the entry for given domain exists, returns AuthData ({ domain: string, token: string }) object.

• set: (authData: AuthData) => Promise<void> - Save auth data.

• delete: (domain: string) => Promise<void> - Remove auth data fot the given domain.

• getAll: () => Promise<AuthData[]> - Returns all auth data available.

• isReady: () => Promise<AplReadyResult> - Check if persistence layer behind APL is ready. For example: database connection established

• isConfigured: () => Promise<AplConfiguredResult> - Check if persistence layer behind APL is configured. For example: env variable required by database connection

AplReadyResult & ApConfiguredResult

Responses from isReady() and isConfigured() should match following:

type AplReadyResult =
  | {
      ready: true;
    }
  | {
      ready: false;
      error: Error;
    };

type AplConfiguredResult =
  | {
      configured: true;
    }
  | {
      configured: false;
      error: Error;
    };

Example implementation

Let's create an APL, which uses Redis for data storage:

import { createClient } from "redis";
import { APL, AuthData } from "@saleor/app-sdk/types/apl";

const client = createClient();
await client.connect();

const redisAPL: APL = {
  get: async (domain: string) => {
    const token = await client.get(domain);
    if (token) {
      return { token, domain };
    }
    return;
  },
  set: async (authData: AuthData) => {
    await client.set(authData.domain, authData.token);
  },
  delete: async (domain: string) => {
    await client.del(domain);
  },
  getAll: async () => {
    throw new Exception("Not implemented.");
  },
};

You'll be able to use it directly:

import { redisAPL } from "./apl";

const createTestData = async () => {
  await redisAPL.set({ domain: "example.com ", token: "test-token" });
};

And with middleware from the SDK:

import { withRegisteredSaleorDomainHeader } from "@saleor/app-sdk/middleware";
import { redisAPL } from "./apl";

const handler = async (request) => {
  return Response.OK({ message: "If you see this, your app is registered!" });
};

// the middleware will reject request if it's domain has not been registered
export default withRegisteredSaleorDomainHeader({ apl: redisAPL })(handler);

Using different APL depending on the environment

Depending on the environment your app is working on, you may want to use a different APL. For example during local development you might like to use FileAPL, because it does not require any additional infrastructure. Deployed apps on the other hand need more robust solution.

To handle both scenarios, initialize the proper APLs in your code based on it's environment. In your application code:

// lib/saleorApp.ts

import { FileAPL, VercelAPL } from "@saleor/app-sdk/APL";

// Based on environment variable the app will use a different APL:
// - For local development store auth data in the `.auth-data.json`.
// - For app deployment on Vercel with Saleor CLI, use vercelAPL.
export const apl = process.env.VERCEL === "1" ? new VercelAPL() : new FileAPL();

Now you can use it for in your view:

import { SALEOR_DOMAIN_HEADER } from "@saleor/app-sdk/const";
import { withRegisteredSaleorDomainHeader } from "@saleor/app-sdk/middleware";
import type { Handler } from "retes";
import { toNextHandler } from "retes/adapter";
import { Response } from "retes/response";

// import created APL
import { apl } from "@lib/saleorApp";

const handler: Handler = async (request) => {
  const saleorDomain = request.headers[SALEOR_DOMAIN_HEADER];

  // Get auth data
  const authData = apl.get(saleorDomain);

  // view logic...

  return Response.OK();
};

export default toNextHandler([withRegisteredSaleorDomainHeader({ apl }), handler]);

Available APLs

FileAPL

File based storage of auth data, intended for local development. Data are stored in the .saleor-app-auth.json file. You'll be able to develop app without additional dependencies or infrastructure.

Please note: this APL supports single tenant only (new registrations overwrite previous ones) and should not be used on production.

VercelAPL

Single tenant APL dedicated for apps deployed on Vercel. Apps deployed from Marketplace and CLI automatically set up Vercel project for this APL (SALEOR_REGISTER_APP_URL and SALEOR_DEPLOYMENT_TOKEN variables).

The auth data are stored using environment variables:

sequenceDiagram
    participant SI as Saleor Instance
    participant A as App
    participant SSI as Saleor x Vercel integration
    participant V as Vercel

    SI->>+A: Register
    A->>SSI: Update auth data
    A->>-SI: Register completed
    SSI->>V: Set auth data as environment variables
    V->>A: Redeploy the application

UpstashAPL

Upstash is a Redis SaaS targeting serverless applications. It's free tier is more than enough to start developing multi-tenant Saleor Apps, and credit card info is not required to create an account.

APL implementation use REST endpoints to store the data, so no extra dependencies are required.

To use UpstashAPL, you'll need endpoint URL and password. Both will be available at dashboard after creating a database. Credentials can be passed to APL during it's creation:

import { UpstashAPL } from "@saleor/app-sdk/APL";

const apl = new UpstashAPL({
  restToken: "XXXXXXXXXXXXXX",
  restUrl: "https://eu2-red-panda-00000.upstash.io",
});

Or using environment variables: UPSTASH_TOKEN, UPSTASH_URL.

RestAPL

RestAPL is a simple CRUD client that performs basic operations on resource provided in constructor

Example usage:

import { RestAPL } from "@saleor/app-sdk/APL";

const apl = new RestAPL({
  resourceUrl: "https://crudcrud.com/api/2c35cdbf2a2c48669b2feda4ab260e1c", // Required, should point to CRUD resource
  headers: {
    Authorization: "Bearer XYZ", // Optional. Headers will be merged into request, allowing to pass auth.
  },
});

Target resource must accept "standard" CRUD operations:

• GET / - get all
• GET /:domain - get AuthData for given domain
• POST / - set AuthData ({domain: string, token: string}) from BODY
• DELETE /:domain - deletes AuthData for given domain