Decide how to handle 3rd party actions

[joshfarrant]

We need to decide how best to store and expose actions from 3rd party apps.

#37 Adds support for Pythonista actions, and it would be good to start as we mean to go on with regards to these actions.

This has briefly been discussed before (here) but it would be good to get more feedback on the correct approach to take.

My main concern is that I don't want the import of these 3rd party actions to be too messy. Ideally we'd have something like:

import {
  editScript,
  runScript,
} from '@joshfarrant/shortcuts-js/actions/pythonista';

We could potentially have something like

import {
  pythonista,
} from '@joshfarrant/shortcuts-js/actions';

const {
  editScript,
  runScript,
} = pythonista;

Which is arguably a bit cleaner, but does introduce the possibility of collisions between app names and built-in action names, which probably rules this option out.

In terms of directory structure we could have:

├─ actions
│  └─ com.omz-software.Pythonista (Alternately this could just be 'Pythonista')
│     ├─ editScript.ts
│     ├─ index.ts
│     ├─ runScript.ts
│  ├─ addToVariable.ts
│  ├─ ask.ts
│  ├─ calculate.ts
│  ├─ ...etc

Does anyone else have any thoughts on this?

[xAlien95]

I would use:

import { pythonista } from '@joshfarrant/shortcuts-js/actions';

pythonista.editScript();
pythonista.runScript();

This would work well also in your site's Playground. Regarding the directory structure, I would prefer to have camelCased folders:

├─ actions
│  ├─ pythonista
│  │  ├─ editScript.ts
│  │  ├─ index.ts
│  │  └─ runScript.ts
│  ├─ addToVariable.ts
│  ├─ ask.ts
│  ├─ calculate.ts
│  ├─ ...

CamelCase will homogenize app names and built-in action names.
It could be based on the app name rather than the last bit of the action identifier, so:

└─ actions
   ├─ editorial
   ├─ pythonista
   └─ tally

[gcordalis]

I think what @xAlien95 has suggested sounds great.

We’ll need to be mindful about naming as some apps will be very similar...

As an example here are 2 of the Carrot apps:

Carrot⁵ (Carrot Weather)
Carrot³ (Carrot Fit)

[bachya]

I like the explicit namespacing of @xAlien95's solution, as well.

[joshfarrant]

I do like that this is quite a clean solution. My only concern with this is that it introduces the possibility of collisions between action names and app names. It’s not unreasonable to think that there could be an app called calculate or list, in which case what would

import { list } from ‘@joshfarrant/shortcuts-js/actions’;

actually import?

Do we just have to make special cases for those and set the app name as listApp?

[gcordalis]

Prefacing each app action group with app[appName] could be a good way to do this. From a folder structure POV it would keep them all together too rather than spread between the native actions in alphabetical order (for the most part)

[joshfarrant]

What about an apps directory in src/actions? You could then do something like:

import {
  pythonista,
} from ‘@joshfarrant/shortcuts-js/actions/apps’;

pythonista.editScript();

We could then also expose an apps variable in the default actions export.

import {
  apps,
} from ‘@joshfarrant/shortcuts-js/actions’;

const {
  pythonista,
} = apps;

pythonista.editScript();

People can then use whichever method they prefer.

[xAlien95]

A user cannot really distinguish a "third-party" action from a "first-party" action, since this attribute isn't explicitly specified in the Shortcuts app.
Do third-party actions refer to those actions that do not have an identifier starting with 'is.workflow.actions.'?

As an example, the Post on Facebook action is a first-party action although it refers to a third-party app, and this may led to confusion.

Post on Facebook => is.workflow.actions.postonfacebook

If in the near future the Facebook app will add support for custom third-party shortcuts actions, then we will have actions in different groups/sub-modules that belong to the same app: the ones starting with 'is.workflow.actions.' and the ones starting with 'com.facebook.' as identifier.

Early, I suggested

pythonista.editScript();
pythonista.runScript();

just to distinguish those actions from future actions that may have a similar or equal shown name.

I would not reject the possibility to call those actions with completely custom names, like

editPythonistaScript();
runPythonistaScript();

if a good documentation is provided on the cool Shortcuts Fun website (really, those css, that editor.. I do really like how you presented that website!).

Can we work on a documentation page in which all the actions are grouped and listed as they shows up in the Shortcuts app? That way users won't have any problems distinguishing all the actions and getting the right function names used in this node module.

[joshfarrant]

Finally made a decision on this and went with @xAlien95's initial suggestion. See #37 for the exact implementation.