ACE Typescript Type Declarations

Atlassian Developer Tools
,
1

Hello everyone,

We have published a beta version of atlassian-connect-express package with typescript type declarations. You can try it out by updating your atlassian-connect-express dependency version to 6.2.3-1. The types can be found in types/index.d.ts of the source and although not entirely complete, they cover most ACE features.

We hope you find these useful. Interested to hear any thoughts, comments or feedback!

7 Likes
2

Hi everyone,

Just an update that these typescript declarations for the atlassian-connect-express package have been released as a non beta version 6.3.0.

Again, interested to hear any feedback!

2 Likes
3

Thank you for the effort of supporting typescript. We are in the process to adapt the official TS implementation.

To implement a typescript rest API library We found it useful to distinguish between different HostClient contexts.

In our case the HostClient methods

asUser(userKey: string): HostClient;
asUserByAccountId: (userAccountId: string|number) => HostClient;

would return an instance with non optional userKey allowing for type guards. This in turn allows us to spot API calls to endpoints not supported for Apps.

4

httpClient(reqOrOpts: { clientKey: string, userAccountId: string })

userAccountId should be optional?

httpClient(reqOrOpts: { clientKey: string, userAccountId?: string }): HostClient;
1 Like
5

Hi,

the current types currently do not allow for a descriptorTransformer adding or manipulation all properties defined in the respective JSON schemas, like e.g. modules, right? Do you plan to maybe generate the descriptor types from their JSON schema and include that for types?

6

Are there any official plans to provide a typescript definition for the client side javascript api? https://developer.atlassian.com/cloud/jira/platform/about-the-connect-javascript-api/
The definitely typed package is lacking here and there

2 Likes
7

Sorry for the lack of responses, all; I wasn’t fully subscribed to this thread and so I only saw the new posts this week. I’ll try to answer one at a time.

8

I can see how it could be useful to distinguish between an “impersonating client” and an “app user client” via the types, although I don’t really understand what you mean by

This in turn allows us to spot API calls to endpoints not supported for Apps.

Do you mean you need the user permission for certain calls, so want to enforce via the types that you’ve got a client that makes requests as a user passed in to certain of your apps methods?

Thanks for the suggestion, but I don’t think we’ll have time to implement that in the types any time soon, sorry. You’re most welcome to raise a PR against Bitbucket with this change.

9

You’re right. userAccountId Should be optional, and doesn’t have any effect, based on my reading of the code and my testing. But it’s probably best to leave it in as optional to avoid a breaking change in the types.

I’ll raise a PR.

10

Hi @UdoHagemannDecadisAG , that’s an interesting idea, but unfortunately we don’t have any plans to add that at this time (but PRs are welcome :smiley: ). If someone were to add that, I suppose the types would need to be different on the bitbucket branch since the schema is different.

11

I believe some people have also experimented with generating a REST client and types from the open API spec available from developer.atlassian.com, although again that’s not something we officially support.

12

I don’t think there are any types for the client side javascript api, or plans to provide them, I’m afraid.

14

Hi @jhazelwood,

Regarding a comment above (ACE Typescript Type Declarations - #4 by Kilian.B) and your PR #244, it doesn’t look like the PR solves the issue.

The PR seems to address the types of the HostClient constructor, but as far as I can tell, this is an internal implementation detail of ACE. The real place where the userAccountId should be marked optional (which is where API clients actually use it) is in the declaration for the AddOn class here:

declare class AddOn extends EventEmitter {
    // ...
    httpClient(reqOrOpts: { clientKey: string, userAccountId: string }): HostClient;
    httpClient(reqOrOpts: express.Request): HostClient;

Is it possible to fix this? This would allow us to call addon.httpClient({ clientKey }) without having to mess with the types.

While we are discussing types, I see that the StoreAdapter interface is missing the getAllClientInfos method. Is this something that could be added too?

Thanks,
Scott

1 Like
15

Hi @jhazelwood ,

I have found a bug in interface StoreAdapter.
I have created a new post because I didn’t know this post.
The post is: https://community.developer.atlassian.com/t/wrong-definition-interface-storeadapter/49122
Basically set function definition is wrong:

interface StoreAdapter {
    del(key: string, clientKey: string): Promise<void>;
    get(key: string, clientKey: string): Promise<any>;
    set(key: string, clientKey: string): Promise<any>;  // Wrong it should be: set(key: string, value: any, clientKey: string): Promise<any>; 
}

Thanks,
Julian

1 Like
16

Thanks @scott.dudley and @JulianMesa , I’ve raised this PR to address the issues you mention. Please let me know if there’s an issue with my fixes, and in future feel free to submit pull requests as well :slight_smile:

17

Thanks, @jhazelwood ! I actually was going to raise a PR, except the project doesn’t seem to accept PRs from non-Atlassians.

Incidentally, we were previously using module augmentation to manually fix the type definitions as needed in our code, but this stopped working somewhere between 6.5.0 and 7.1.x. I think this is related to the fact that some of the classes (eg. AddOn) are no longer being directly exported, but you are instead declaring an AddOnFactory which exports copies of those types.

I admittedly spent only 15 minutes trying to figure it out in the new format before giving up and slapping in some @ts-ignore’s. It would be nice if this were possible given that we don’t always necessarily want to upgrade ace (or wait for PR acceptance) just to get the correct types for something that was accidentally omitted in the published package.

2 Likes
18

You should be able to raise PRs by forking the repo. See, for example: https://bitbucket.org/atlassian/atlassian-connect-express/pull-requests/254 raised by @KaitoUdagawa who is not an Atlassian. I think that PR might also be the change you’re talking about that led to module augmentation no longer working, and it appears to have been done to add flexibility around the consumer’s esModuleInterop options. I didn’t review that one though so I don’t know the details.