Assistants web service

[jedrichards]

Assistants will benefit from web services that performs the following tasks:

1. Facilitates one-click installs (required for launch)
2. Sits in-between Sketch and the npm registry API, and provides Assistant package metadata (only required once we add support for Npm Assistants to Sketch, not required while we only support Url Assistants)

Read on more for more details.

Glossary

• Url Assistant An Assistant added to a Sketch document via a name and a fully qualified url to a hosted tarball. This sort of Assistant is technically unversioned, it just exists at a url.
• Npm Assistant An Assistant added to Sketch via a npm package name and semver. This sort of Assistant is versioned, and Sketch will be able to let a user know when the Assistant in their document can be updated etc.

  One click installs

Using a web service here, instead of users crafting the sketch:// protocol deep-links themselves gains us the following advantages:

• One click install links can be added to websites that strip non-standard protocols from links (i.e. GitHub)
• We can find out the latest version of the package automatically, rather than a user having to keep their links up to date
• If we need to change something about the implementation in Sketch, or adjust the protocol we have a central place to do that, without invalidating links in use by 3rd parties
  • Example of this will be when we transition from only supporting Url Assistants to supporting Npm Assistants we can just make that change in this web service and change the behaviour centrally

Already have a proof of concept that is being used in the wild at the moment, so should just be a case of reworking this.

Url Assistants behaviour

This is the behaviour of the current proof of concept.

1. User clicks a link to the service, indicating the npm package name of the Assistant they want to add to their Sketch document
2. Various options can be supplied (e.g. tag or latest version etc, Sketch variant for the deep link etc.)
3. The service queries the npm API to resolve a fully qualified tgz url for that Assistant package
4. The service redirects to the sketch:// deep link protocol, and asks the Sketch to add it as a Url Assistant

Npm Assistant behaviour

This won't be required until we support Npm Assistants.

Path and options would change minimally between the two behaviours, so we could just switch it over when Npm Assistants are released.

1. User clicks a link to the service, indicating the npm package name of the Assistant they want to add to their Sketch document
2. Various options can be supplied (e.g. tag or latest version etc, Sketch variant for the deep link etc.)
3. The service queries the npm API to determine which semver should be used
4. The service redirects to the sketch:// deep link protocol, and asks Sketch to add it as a Npm Assistant

Sketch Npm Proxy

This won't be required until we support Npm Assistants.

This could begin life as a single endpoint, where Sketch could ask for metadata about Npm packages, and get back information.

Using a web service here will insulate Sketch from any changes or rough edges in the npm API.

• List available versions for each Assistant
• Expose human readable metadata for each Assistant for display in Sketch UI
• List full tarball urls for each version
• List any tags (there'll always be at least a latest tag, for example)

So if Sketch posted the following JSON to the endpoint (i.e. one or more Assistant names)

[
  "@sketch-hq/sketch-tidy-assistant"
]

It would get back something like

{
  "@sketch-hq/sketch-tidy-assistant": {
    "title": "Tidy Assistant",
    "description": "Blah",
    "icon": "https://www.domain.com/icon.png",
    "tags": {
      "latest": "5.0.1"
    },
    "versions": {
      "5.0.1": "https://registry.npmjs.org/@sketch-hq/sketch-tidy-assistant/-/sketch-tidy-assistant-5.0.1.tgz",
      "5.0.0": "https://registry.npmjs.org/@sketch-hq/sketch-tidy-assistant/-/sketch-tidy-assistant-5.0.0.tgz",
      "4.1.0": "https://registry.npmjs.org/@sketch-hq/sketch-tidy-assistant/-/sketch-tidy-assistant-4.1.0.tgz",
      ...
    }
  },
  ...
}

Technology choices

• Are we happy with Vercel?
  • It natively supports TypeScript, which is nice
• Are there other options? Netlify functions?
  • Netlify functions seem a little more basic than Vercel (no edge caching, locked to US AWS region by default, no TypeScript support)
• Something more homegrown, and/or owned by our backend team?
• Scalability?

Domain

Perhaps something like assistants.sketch.com?

[craig006]

@jedrichards it looks good to me.

One thing we could consider adding to the response from our "npm proxy", is some of the localized data, if that is possible. This would be useful when opening a document with a missing assistant to allow us to still display a friendly, title, description and perhaps even the icon, before the user chooses to hit the install button. But happy to not do this if you guys don't think its worth it.

Example:

[christianklotz]

@luisbosque would be good to get your thoughts on it 🙏

[luisbosque]

After talking with @christianklotz setting up this backend service seems like too much complexity for what we try to achieve here. The logic to redirect to a sketch:// url seems like something that could perfectly happen in the assistants' webpage in JS or another approach would be to pre-generate the sketch:// urls of the different assistants during the deployment.

This will make a much simpler architecture, easier to maintain and prevent us to have to maintain a new service.

[jedrichards]

Agreed that extra services/moving parts aren't all that desirable.

If we're ditching the one-click web service we need to be clear on the implications:

• Pre-generating the sketch:// links on sketch.com would mean they could quickly get stale, since they'll point to fully qualified tarballs urls on npm (e.g. https://registry.npmjs.org/@sketch-hq/sketch-tidy-assistant/-/sketch-tidy-assistant-5.0.0.tgz) so if new versions of the Assistant were released between builds of sketch.com they wouldn't get picked up
• The above would mean sketch.com would instead have to implement client side interaction with npm, and then redirect when the install button was clicked. This adds complexity to the website and would make the feature inoperable without JS enabled, but I can't see any other reason why it wouldn't work.
• The main downside is that an Assistant install feature/button would not be conveniently implementable by 3rd parties on their own websites, private pages or intranets
• Users won't be able to add Assistant install buttons to GitHub readmes
• We won't have a centralised place to change or fix issues with the sketch:// protocol

None of the above are deal breakers though, so if we're ok with them we should brief the web marketing team about the extra requirement asap.

[christianklotz]

Closing for now, as #118 is handled separately.