google_api.atd

(* https://developers.google.com/accounts/docs/OAuth2WebServer *)

type uid <ocaml from="Core" t="uid"> = abstract
type token <ocaml from="Core" t="token"> = abstract
type scope = string wrap <ocaml module="Google_scope">
type email = string wrap <ocaml module="Email">
type teamid = string wrap <ocaml module="Teamid">

type oauth_token_result = {
  ?access_token : string option;
  ?refresh_token: string option;
  ?expires_in   : float  option;
  ?error        : string option;
}
(*
  Google will respond to your POST request by returning a JSON object
  that contains a short-lived access token and a refresh token.
{
  "access_token" : "ya29.AHES6ZTtm7SuokEB-RGtbBty9IIlNiP9-eNMMQKtXdMP3sfjL1Fc",
  "token_type" : "Bearer",
  "expires_in" : 3600,
  "refresh_token" : "1/HKSmLFXzqP0leUihZp2xUt3-5wkU7Gmu2Os_eBnzw74"
}
*)

(*
   State passed along during the Google OAuth process.
*)
type state = {
  ?login_nonce: string option;
    (* Secret chosen by the client and passed through Google authentication
       to the Esper server.

       1. Client starts the oauth process, passing this newly-generated
          secret to Google.
       2. Once the user is authenticated with Google, Googles posts
          the secret to Esper. Esper now knows that this secret belongs to
          the Google account owner.
       3. At the end of the oauth process, the user is redirected to an
          Esper page.
       4. The secret is posted from the Esper page, and the Esper server
          responds with login info, including the api_secret that
          will be used for Esper API queries.
    *)

  ?invite: token option;
    (* invite token, which results in the creation of an api_secret for
       the user, making the user a full Esper member. *)

  ?ok_url: string option;
    (* landing URL when everything was successful *)

  ?authorized_for: authorized_party option;
    (* The token is to be shared to an existing team,
       not to create a new user account. *)
}

type authorized_party = {
  uid: uid;
  teamid: teamid;
} <ocaml field_prefix="state_">


(*
   There's no official documentation for those fields.

   (the closest official documentation is the one given here:
   https://developers.google.com/accounts/docs/OpenIDConnect#obtainuserinfo
   all fields are abbreviated but seem to match what we get here.)

   Look into the libraries provided by Google for more assurance.
*)
type id_token_info = {
  issuer    : string;        (* "accounts.google.com" *)
  audience  : string;        (* our client ID *)
  expires_in: float;         (* seconds *)
  issued_at : float;         (* date *)
  ?email    : email option;  (* user's authorization email *)
  (* more fields omitted *)
} <ocaml field_prefix="id_token_">


(*
   Only an incomplete "type" is given by the official documentation.
   https://developers.google.com/accounts/docs/OAuth2UserAgent#validatetoken

   Try:
     curl https://www.googleapis.com/oauth2/v1/tokeninfo?access_token=...

   (works only with an access_token, not directly with a refresh_token)
*)
type access_token_info = {
  audience: string;
    (* The application that is the intended target of the token.
       (our client ID) *)

  scope: scope;
    (* The space-delimited set of scopes that the user consented to. *)

  ?user_id: string option; (* e.g. "user_id": "111908179428740497447" *)
    (*
       This field is only present if the profile scope was present in
       the request. The value of this field is an immutable identifier
       for the logged-in user, and may be used when creating and
       managing user sessions in your application. This identifier is
       the same regardless of the client ID. This provides the ability
       to correlate profile information across multiple applications
       in the same organization.

       Note: official doc in one place refers to 'userid'. It is 'user_id'.
    *)

  expires_in: float;
    (* The number of seconds left in the lifetime of the token. *)


  (*** Undocumented fields found in Google responses ***)

  ?email: email option;
  ?verified_email: bool option;
  ?access_type: string option; (* e.g. "offline" *)

} <ocaml field_prefix="access_token_">