Add Type Definitions so can be easily be used in a TypeScript project

[okta]

Add Type Definitions so can be easily be used in a TypeScript project

[robertjd]

Hi everyone, thank you for your thoughts. We've discussed this and have decided that Typescript should get some first-party support from us, so we will start working it into our roadmap. Continue to watch this issue for updates. Thanks!

[codeaid]

After not finding any decent type definitions for version 2 I decided to go through the documentation and compile my own. As I'm only using the web flow, I've not covered the session related methods or transactions (or any methods on the main client for the matter of fact) but nonetheless I think it's a good start.

You can find them here in a gist I've created: https://gist.github.com/codeaid/1deacf28ab56cea3b715e83e520aae32

I don't think it would take much work to complete them so let me know if anyone's interested in having this finished and we can think about 😉

[danielsig]

Here, I made a little something to get people started on their own.
Paste it in your code where you use okta.
Or put it in it's own file, but then you must remember to add the "export" in front of every interface and also in front the class declaration at the bottom.
I made a loose definition of IPromise<T> at the bottom. If you already have a definition of Promises (e.g. AngularJS's ng.IPromise<T> or Angular's Promise<T> then I encourage you to use that instead.

	/** OktaAuth TypeScript Definitions */

	interface OktaConfig
	{
		url:string;
		clientId?:string,
		redirectUri?:string;
		issuer?:string;
	}
	interface OktaCredentials
	{
		username:string;
		password:string;
	}
	interface OktaTransaction
	{
		readonly status:string;
		readonly sessionToken:string;
		cancel():IPromise<OktaTransaction>;
	}
	interface OktaOAuthOptions
	{
		responseType:string|string[];
		sessionToken?:string;
	}
	interface OktaToken
	{
		getWithoutPrompt(oauthOptions:OktaOAuthOptions):IPromise<any>;
		getWithPopup(oauthOptions:OktaOAuthOptions):IPromise<any>;
		getWithRedirect(oauthOptions:OktaOAuthOptions):void
		parseFromUrl():ng.IPromise<any>;
		decode(idTokenString:string):string
		refresh(tokenToRefresh:string):IPromise<string>;
		getUserInfo(accessTokenObject:string):IPromise<any>;
		verify(idTokenObject:string):IPromise<any>;
	}
	interface OktaTokenManager
	{
		/** After receiving an access_token or id_token, add it to the tokenManager to manage token expiration and refresh operations.
		*	When a token is added to the tokenManager, it is automatically refreshed when it expires.
		* @param {string} key Unique key to store the token in the tokenManager. This is used later when you want to get, delete, or refresh the token.
		* @param {string} token Token object that will be added */
		add(key:string, token:string):void;
		/** Get a token that you have previously added to the tokenManager with the given key */
		get(key:string):string;
		/** Remove a token from the tokenManager with the given key. */
		remove(key:string):void;
		/** Remove all tokens from the tokenManager. */
		clear():void;
		/** Manually refresh a token before it expires. */
		refresh(key:string):void;
		/** Subscribe to an event published by the tokenManager. */
		on(event:'expired'|'error'|'refreshed', callback:Function, context?:any);
		/** Unsubscribe from tokenManager events. If no callback is provided, unsubscribes all listeners from the event. */
		off(event:'expired'|'error'|'refreshed', callback:Function);
	}
	declare class OktaAuth
	{
		readonly token:OktaToken;
		readonly tokenManager:OktaTokenManager;
		constructor(config:OktaConfig);
		public signIn(options:OktaCredentials):IPromise<OktaTransaction>;
		public signOut():IPromise<any>;
		[fn:string]:any;
	}

The code below is mostly for those who don't already have promises in their project. If you use AngularJS or Angular, just use their definitions instead and change the code above accordingly.

	interface IPromise<T>
	{
		then(onSuccess:(arg:T)=>any):IPromise<any>;
		then<TOut>(onSuccess:(arg:T)=>TOut):IPromise<TOut>;
		catch(onReject:(err:any)=>void):IPromise<void>;
		finally(finallyCallback:()=>void):IPromise<void>;
	}

[codeaid]

Don't want to be harsh but I think it's appalling that in this day and age one of the largest OIDC providers hasn't bothered to add TypeScript support for their SDK and people have to resort to hacking their own definitions. Even libraries like oidc-client-js have full support but unfortunately the library doesn't work when it comes to refreshing tokens as Okta decided to require Basic authentication during the call to /token endpoint which no-one else does.

To add insult to the injury - this issue has been open for 2 years now with nothing coming out of it!

[nbarbettini]

Thanks for the feedback @codeaid. This is something I'd like to do, but we've had higher-priority features and bug fixes in the pipeline for a while. Sorry about the lack of TypeScript love. I'm leaving this open to continue to collect votes and +1s for TypeScript definitions.

I'm not sure why oidc-client-js wouldn't work with Okta's endpoints. Their library is spec-compliant, and so are our endpoints. Okta supports all of the client authentication styles defined by the spec, including client_secret_post (and client_secret_basic, as you mentioned). Maybe is a configuration error in that case?

[Hanzalah-Adalan]

just lazily hacked the errors by suppressing them with //@ts-ignore
I'm done...🤣🤣🤣🤣🤣

[carnesen]

Absent typings included in the package, our best bet is to collaborate on community-provided typings in the DefinitelyTyped project.

[shihlinlu]

When do you expect for the the Type definitions to be available?

[swiftone]

@shihlinlu (and the many interested) - we try our best not to make promises we may then not make because of the reality of software development, so all I can say is that we are well aware of the interest in adding these definitions and appreciate your (enthusiastic!) patience.

...which may not be a satisfying answer, but it is a sincere one.

[shuowu]

Typescript is supported in okta-auth-js since v4.0. Please see the migration guide to upgrade.

[swiftone]

@codeaid - Thanks for sharing! When we're ready to support and maintain TS definitions, we would love to consider your code - are you willing to sign a CLA for us? (https://developer.okta.com/cla/ ) I don't know if one is legally required, but better safe than sorry.

Either way, I'm sure others appreciate you sharing your efforts!

[xenoterracide]

+1

[swiftone]

Internal ref: OKTA-241766

[nick-myers-dt]

Also the comment about not making promises because of the nature of software development is disingenuous at best. Problems that are prioritised get done. This comment belies a reality which says "we don't care about this" or worse "we want to do this but our management won't let us".

[shellscape]

@shuowu worth noting that @okta/jwt-verifier has no types.

[Savij]

These are basically standard for any package at this point. Please add them!! Pretty please?

[squarewave24]

Here, I made a little something to get people started on their own.
Paste it in your code where you use okta.
Or put it in it's own file, but then you must remember to add the "export" in front of every interface

doesn't seem to correspond with what i'm seeing.. for example props.auth object looks like this:

handleAuthentication: ƒ, isAuthenticated: ƒ, …}
getAccessToken: ƒ ()
getIdToken: ƒ ()
getUser: ƒ ()
handleAuthentication: ƒ ()
isAuthenticated: ƒ ()
login: ƒ ()
logout: ƒ ()
redirect: ƒ ()
...

[erichulburd]

When do you think you'll be ready to support and maintain TS definitions @swiftone ?

[swiftone]

@erichulburd - great question! I don't set the timeline for such features and don't to create a false expectation by giving a commitment I (or anyone else on the team) can't meet, but I'd venture it is safer to use the workaround provided by @codeaid over waiting for a change - we have an investigation task but nothing will happen rapidly.

[nick-myers-dt]

We have just signed an agreement with Okta and are only now realising that Okta has claimed to have this on their roadmap for many years now. We're going to cancel and find a different provider. This sort of thing is third-rate.

[mraible]

@nick-myers-dt I agree it's taking a while. I'm a big fan of TypeScript and I've used it with many of our JS SDKs. The good news is there's an active pull request in the works. See #380 for more information.

[Richifg]

+1