Fix @types/auth0 inconsistencies with this library

[vicary]

Describe the problem

Relocated from community forum (53190).

From earlier technical support enquiries I know that the SDK method ManagementClient#passwordGrant() in fact takes an undocumented second argument { forwardedFor } to sent the Auth0-Forwarded-For header. Since server-side authentication requires the option to prevent blocking, I would like to know if there are plans to add the definition in the official SDK documentation?

The TypeScript/DefinitelyTyped community is confused about this and I think we need official comments to move on.

What was the expected behavior?

https://auth0.github.io/node-auth0 and @types/auth0 should reflects the implemented features and actual behaviour of this repo.

Reproduction

npm install @types/auth0

Environment

• Version of this library used: 2.20.12
• Which framework are you using, if applicable: Serverless
• Other modules/plugins/libraries that might be involved: DefinitelyTyped, TypeScript
• Any other relevant information you think would be useful: N/A

[davidpatrick]

Thanks @vicary for raising the issue. Let me talk with the team about the possibility of bringing the types into this library.

[franklin-ross]

I just came across this myself by tracing through the code and noticing the hidden extra param. At the very least, could someone move on updating the docs where they are? Moving them here would be great, but sounds less quick.

[vicary]

I just came across this myself by tracing through the code and noticing the hidden extra param. At the very least, could someone move on updating the docs where they are? Moving them here would be great, but sounds less quick.

We the community may trace out types (i.e. @types/auth0) according to official documentations (i.e. https://auth0.github.io/node-auth0). But it is really not easy for others to reverse engineer the whole thing from source, let alone keeping up with changes here in this repo.

[davidpatrick]

Thanks @vicary and @franklin-ross for raising visibility. We agree that maintaining the types in this library is the correct path. Let me discuss with the team on the best path forward for migration.

[danawoodman]

Another mismatch is the management.getUser() API which the type says returns an object of the user attributes but instead returns an array of a single user object. Either the library should return 1 result (as you would expect) or the types should be adjusted 👍

[vicary]

@danawoodman I think your issue should be tracked separately, yours could be a documentation mismatch, or a genuine implementation mistake.

This issue is about TypeScript types matching the current codebase AND documentations, not the other way around.

[franklin-ross]

I noticed a few others: getJobErrors() and importUsersJob() exist and can be called, but aren't documented on the types at all. It's especially confusing because importUsers() does exist in the types, but is deprecated and suggests using importUsersJob() which doesn't show up in the editor.

[stevehobbsdev]

Thanks for continuing to raise these discrepancies @franklin-ross. We've had conversations within the team and we do want to take ownerships of these types. Not sure what that looks like yet and it's a matter of prioritization; as soon as we have an update to share, we'll post it here.

[thgh]

Not sure if this requires a new issue, but I notice a lot of optional fields and I don't understand how this could happen.

e.g. AuthenticationClient

or Connection, it would be interesting to include a comment that explains why it might be missing.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. If you have not received a response for our team (apologies for the delay) and this is still a blocker, please reply with additional information or just a ping. Thank you for your contribution! 🙇‍♂️

[vicary]

Pinging @davidpatrick because this should not be stale.

[kkomelin]

We miss Organizations types. Please add to ether @types or to this project. Thanks in advance.

[sukruavcuoglu]

any estimation for adding Organization types?

[namoscato]

In the meantime, you can augment the DefinitelyTyped definitions with a module in your own codebase, i.e.

import * as auth0 from "auth0";

declare module "auth0" {
  /**
   * @see https://auth0.com/docs/api/management/v2/#!/Organizations/get_organizations
   * @see https://auth0.github.io/node-auth0/module-management.OrganizationsManager.html
   */
  export interface OrganizationsManager {
    getEnabledConnections({
      id: string,
    }): Promise<
      Array<{
        connection_id: string;
        assign_membership_on_login: boolean;
        connection: {
          name: string;
          strategy: string;
        };
      }>
    >;
  }

  export interface ManagementClient {
    organizations: OrganizationsManager;
  }
}

Realistically, I don't have time to help out with all of these definitions but am happy to help out with what I can. We really just need some clarity from Auth0 on how and when the TypeScript support for this library evolves. From all of us on this thread, thank you in advance for your efforts around prioritization!

[omnibrain]

Sorry for asking again, but any news on the organization types? This really slows us down 😞 If at least we had some idea when we can expect the types to be implemented so we could decide if we should do it ourselves or wait for the official types.

Or does anyone in this thread maybe have an implementation that we could use as a basis?

[frederikprijck]

Support for Organizations has been added as part of "@types/auth0": "^2.34.0",, if you update to the latest version you should be able to use client.organizations.getAll() etc.

[kkomelin]

That's very good news @frederikprijck! Thank you very much to you and everyone who was involved in delivering the Organizations API support.

[mistycal98]

Support fot UserManager in @types/auth0 for nodejs currently only organizations is available

Example

const auth0 = new ManagementClient(options);

auth0.users.                     // users not found

[Roustalski]

Any update here or ETA? Is this still in the backlog or prioritized to have this worked soon?

[prattcmp]

+1. Is this prioritized in the backlog?

[ALVNCHNG]

+1 for this. Having some typing issues especially on AuthenticationClient

[jonasschultheiss]

Please add the types in this repo. i have to check if a user is in an organisation and it's a pain to do it without this function: https://auth0.github.io/node-auth0/UsersManager.html#getUserOrganizations

[Stono]

Probably related:

• Types for getClients, getResourceServers, when using include_totals are incorrect #733
• Types for getResourceServers is missing include_totals #732

[jdjkelly]

@kkomelin is right:

@vicary I agree that it should be an SDK team responsibility to support the typings. And it may not be that hard because TypeScript compiler can actually generate typings by JS files.

npx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly --outDir types

Creating .d.ts Files from .js files

• The library should prioritize emitting TS typings and ensuring types is in the release using the one liner above.
• Missing types on UserManager for example missing getUserOrganizations https://auth0.github.io/node-auth0/UsersManager.html#getUserOrganizations force implementer use of any
• @types/auth0/DefinitelyTyped mentioned in the root of the is project is a separate concern. node-auth0 should emit its own types first. See more in this Stackoverflow answer.

[Alex-Yakubovsky]

@jonasschultheiss I needed getUserOrganizations as well; I put a PR to add the type definition

[alejandromcsd]

@frederikprijck could you please share an update on typings for node-auth0? Is this library still a priority for Auth0 or should customers be using a different SDK for building Node apps that require interacting with Management API?

Seems like this issue has been opened for almost 2 years, and yet there are many typings missing, e.g. management.regenerateRecoveryCode.

[adamjmcgrath]

Hi @alejandromcsd - thanks for your feedback. This library still relies on the DefinitelyTyped for it's types, and we currently don't have a timeline on when that may change. We'll update this thread when we have any news.

[Aaronius]

I'm looking for types for action functions, specifically the parameters. For example:

exports.onExecutePostLogin = async (event: any, api: any): Promise<void> => {
  
}

Does anyone have proper types for action functions like these? Or even a stab at them?

[jfromaniello]

Not sure if this helps or if it should be the route to take but it seems since Typescript 3.7 the compiler can generate the types from JS files with jsdoc params. Fortunately this library has some quite good jsdocs, so I tried it and I've to say that I am impressed by the results:

Here are the changes https://github.com/auth0/node-auth0/compare/master...jfromaniello:node-auth0:with_types?expand=1

As you can notice I didn't add the types to the repo, just added a prepare script to generate them. It also has the declaration map, which makes "go to definition" in vscode works nice.

You can try it out with npm i 'jfromaniello/node-auth0#with_types' --save

[vicary]

@jfromaniello This is definitely an interesting approach! But after installing your fork I found that intermediate types are not nearly enough, for example we heavily relies on a generic type AppMetadata<{...}> in our codebase and it is nowhere to be found.

I would suggest a hybrid approach, where methods in AuthenticationClient and ManagementClient are generated from jsdoc, while intermediate types are maintained in separate .d.ts files.

[jfromaniello]

@vicary yes, I think that's a better idea 👍🏽

[jfromaniello]

We could also put some of these types from @types/auth0 like AppMetadata into a .d.ts file then in the js:

/**
 * @typedef { import("./types").AppMetadata } AppMetadata
 * @typedef { import("./types").UserMetadata } UserMetadata
 * @typedef { import("./types").UserData } UserData
 */

and use these types in the jsdocs:

 /**
   ....
   * @param   {object}      params      The user data object..
   * @param   {string}      params.id   The user id.
   * @param   {AppMetadata} metadata    New user metadata.
   * @param   {Function}    [cb]        Callback function
   * @returns  {Promise|undefined}
   */
  updateUserMetadata(...args) {

[vicary]

@jfromaniello This looks promising!

[jfromaniello]

@vicary I added just AppMetadata and UserMetadata to my branch, just in case you can check it out

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. If you have not received a response for our team (apologies for the delay) and this is still a blocker, please reply with additional information or just a ping. Thank you for your contribution! 🙇‍♂️

[shellscape]

@jfromaniello @Widcket @types/auth0 doesn't match the API surface of the package as outlined here https://auth0.github.io/node-auth0. For instance, actions doesn't appear in the types at all. And it looks like much of the interfaces haven't been updated after the latest major version of node-auth0

FWIW this fork https://github.com/jfromaniello/node-auth0 is 41 commits behind upstream.

We're a few years on now from when the original discussion was started on the community site, and we (customers) still lack up to date TypeScript types for the first-class API for auth0. Please advise.

[adamjmcgrath]

Thanks for raising this @shellscape - we are actively developing a TypeScript version of this library and we hope to have a Beta out in the next few weeks.

You can follow the progress in the beta branch - for example see the ActionsManager.ts

[shellscape]

@adamjmcgrath thanks for the update. would it be possible to have your team publish the beta to a dist-tag as work is done?

→ npm info auth0 dist-tags
{
  latest: '3.3.0',
  alpha: '2.0.0-alpha.3',
  'alpha.4': '2.0.0-alpha.4',
  'alpha.5': '2.0.0-alpha.5'
}

A tagged alpha release would be preferable, but we can fall back to forking and publishing to a scope if absolutely necessary. (I thought that perhaps a github dependency might work but the branch isn't setup for that)

[adamjmcgrath]

Thanks @shellscape - we'll publish a beta as soon as it's available, we don't publish anything on npm before that - but you can publish your own under a scope or use a tarball in the interim.

I thought that perhaps a github dependency might work but the branch isn't setup for that

You could probably also do this if you setup typescript to transpile node_modules/auth0

[adamjmcgrath]

I'm pleased to report that the Beta of v4 is now available. This has been rewritten in TypeScript and has full type coverage of Auth0's Management and Authentication APIs.

Closing this thread in favour of #859

[shellscape]

thanks for the update

[vicary]

@adamjmcgrath Thanks the auth0 team for making it happen!

[vicary]

[email protected] does not load the types in VS Code, my repo is a freshly created Next 13 and it is loading cjs.

[adamjmcgrath]

Thanks for reporting this @vicary - this should be resolved in 4.0.0-beta.2