FIP: Standard file format to import/export Mini App subscriptions

[vrypan]

Title: Standard file format to import/export Mini App subscriptions
Type: Standards FIP
Authors: @vrypan

Abstract

Define a standard file format that can be used to import/export Mini App subscriptions

Problem

A Mini App subscription allows a Mini App to sent notifications to an FID on a specific Farcaster client.

There are currently at least two providers that offer notifications as a service, Neynar and Pingem, and many
developers have implemented their own notification backends. Also, Warpcast recently started offering the option
to export a Mini App's subscriptions.

When a developer decides to move their Mini App subscriptions between one of the available solutions (own, Neynar, Pingem, possibly other), they need to have a standard format that will make this move easier: export from A, import to B.

We also have tools that allow non-technical users to maintain simple Mini Apps, and they should be able to move subscriptions between services, too.

Specification

JSON schema

The proposed format to exchange Mini App Subscriptions is a JSON file with the following schema.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ClientSubscriptionsList",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "clientFid": {
        "type": "integer"
      },
      "endpoints": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "endpoint": {
              "type": "string",
              "format": "uri"
            },
            "subscriptions": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "fid": { "type": "integer" },
                  "token": { "type": "string" },
                  "subscribed": { "type": "boolean" }
                },
                "required": ["fid", "token", "subscribed"]
              }
            }
          },
          "required": ["endpoint", "subscriptions"]
        }
      }
    },
    "required": ["clientFid", "endpoints"]
  }
}

Based on this schema, the current Warpcast export will look something like this:

[
  {
    "clientFid": 9152,
    "endpoints": [
      {
        "endpoint": "https://api.warpcast.com/v1/frame-notifications",
        "subscriptions": [
          {
            "fid": 1001,
            "token": "550e8400-e29b-41d4-a716-446655440000",
            "subscribed": true
          },
          {
            "fid": 1002,
            "token": "",
            "subscribed": false
          }
        ]
      },
    ]
  }
]

Filename extension

If the export is provided as a file, the proposed extension is .fcs, for Farcaster subscriptions.

Rationale

The schema supports:

• multiple clients: Warpcast, Coinbase, Zapper, etc
• multiple endpoints per client: Clients may define multiple endpoints for various reasons, including sharding, or migrating to new domains, new API versions, etc.

The schema will work both for clients (ex. Warpcast export) and services like Neynar and Pingem.

It is also self-contained, and does not require for the user to provide additional context (for example, the current, flat-file export by Warpcast will require a user to provide the endpoint, and the client name). In theory, a non-technical user should be able to export subscriptions from one service as a file, and import them to an other.

Having a pre-defined file extension makes it easy to write documentation and explain a process to users: "Click here to upload your FCS file", "Export your FCS file and..."

[deodad]

wdyt of a simple csv like what warpcast does but with clientFid and endpoint as two additional columns?

easier to generate and ingest

[vrypan]

Would be ok (same info).

Two (not so important) cons:

• File size will grow faster (IF clients don't decide to use a unique endpoint for every subscription, in which case the csv may be smaller). Larger file -> more memory required.
• Additional info is harder to include in a way that is compatible between different systems. For example, Farma can include first_seen_date, and Naynar can include last_seen_date, and both files will be compatible without additional changes to the import code. If a CSV is used, then you will have to know in advance what the last column means.