taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

register-alias.rst (1838B)

      1 .. ts:op:: registerAlias
      2 
      3   Initiate the registration of an alias with a taldir (directory)
      4   service.  The alias (for example an e-mail address or a phone
      5   number) is associated with a target URI, typically the wallet's
      6   mailbox URI.  Unless the registration is already paid for, the
      7   service sends a challenge to the alias; the registration is
      8   completed with :ts:op:`completeRegisterAlias` once the user has
      9   received the challenge.
     10 
     11   **Request:**
     12 
     13     The request arguments are a `TaldirRegistrationRequest` object.
     14 
     15   **Response:**
     16 
     17     On success, the result is a `TaldirRegistrationResponse`: an empty
     18     object if a challenge was sent to the alias, or a
     19     `TaldirAlreadyPaidResponse` object if the registration already
     20     exists and is still paid for.
     21 
     22   **Side effects:**
     23 
     24     Requests the alias registration at the taldir service over the
     25     network; the service may require payment for the registration.
     26 
     27   **Expected errors:**
     28 
     29     The caller can handle the following errors inline:
     30     ``WALLET_ALIAS_REGISTRATION_FAILED``.
     31 
     32 .. ts:def:: TaldirRegistrationRequest
     33 
     34   interface TaldirRegistrationRequest {
     35     // Alias to register, in alias-type-specific format.
     36     alias: string;
     37 
     38     // Type of the alias, e.g. "email" or "sms".
     39     aliasType: string;
     40 
     41     // Target URI to associate with the alias.
     42     targetUri: string;
     43 
     44     // Base URL of the taldir service.
     45     taldirBaseUrl: string;
     46 
     47     // For how long the registration should last or be extended.
     48     duration: RelativeTime;
     49   }
     50 
     51 .. ts:def:: TaldirRegistrationResponse
     52 
     53   type TaldirRegistrationResponse =
     54     | TaldirAlreadyPaidResponse
     55     | EmptyObject;
     56 
     57 .. ts:def:: TaldirAlreadyPaidResponse
     58 
     59   interface TaldirAlreadyPaidResponse {
     60     // The remaining duration for which this registration is still
     61     // paid for.
     62     valid_for: RelativeTime;
     63   }