@polar-sh/astro

[isaacharrisholt]

After some discussion with @birkjernstrom, I've decided to create an Astro integration for Polar. I've written a little design doc (below). Please let me know your feedback!

The goal

A simple-to-use SDK (@polar-sh/astro) for integrating Astro sites with Polar.

Requirements

Note: the versioning here does not comply with semver, and is mostly to determine the order of priorities.

V1

• SDK can push Astro markdown blog articles to Polar via the API
  • If the article already exists, the article should be updated
  • Idempotency key is the article slug

V2

• SDK includes functions and documentation for authenticating users on the Astro site using Polar
• SDK includes Polar-specific components like <Paywall>
  • Since Astro supports React components, these can be shared with the main app
• Should contain helper methods for determining a user's subscription tier etc.

V3

• SDK can pull Polar articles and generate static or SSR pages in Astro sites

API

I suggest using a builder pattern for the API that allows users to transform and filter articles based on the Astro frontmatter data and entry properties.

For example:

const blogPosts = await getCollection('posts')
const polar = new Polar({ apiKey, organizationId })

const { data, error } = await polar
  .upload(blogPosts)
  .transform(({ entry, article }) => {
    // Add featured image to article
    article.body = `![](${entry.featuredImage})\n${article.body}`
	return article
  })
  .filter(({ exists }) => {
    // Don't update articles that have already been uploaded
    return !exists
  }) 

This could be achieved using a construct like a PolarUploadBuilder class, for example:

type BuilderFunctionDefinition = {
  type: 'filter',
  function: FilterFunction
} | {
  type: 'transform',
  function: TransformFunction
}

class PolarUploadBuilder {
  private functionPipeline: BuilderFunctionDefinition[]
}

Thus the types in the above example would look like so:

const blogPosts = await getCollection('posts')  // CollectionEntry<'posts'>
const polar = new Polar({ apiKey, organizationId })  // Polar

const { data, error } = ( // PolarResult<UploadResponse, UploadError>
  await polar             // Polar
    .upload(blogPosts)    // PolarUploadBuilder<'posts'>
    .transform()          // PolarUploadBuilder<'posts'>
    .filter()             // PolarUploadBuilder<'posts'>
)

Where:

type PolarResult<T, E = Error> = {
  data: T,
  error: null
} | {
  data: null,
  error: E
}

The way we avoid early execution of the upload is by making PolarUploadBuilder extend the PromiseLike<PolarResult<...>> type, where the .then() method contains the upload logic.

We can then use a similar pattern for downloading articles when we get to implementing V3 of the package.

I also recommend the Polar class has a public client: PolarAPI property to allow users to interact with the API directly if so desired. By having @polar-sh/sdk as a peer dependency, we can ensure users can always have up-to-date API access without having to manually update this package.

Discussion points

• Default behaviour when no transform function is provided
  • e.g. default values for visibility, publish_date, title, etc
• Alternative patterns/implementations