====================================
Common LibEuFin HTTP API Conventions
====================================


Contact details
^^^^^^^^^^^^^^^

.. ts:def:: EmailAddress

  type EmailAddress = string;

.. ts:def:: PhoneNumber

  type PhoneNumber = string;

Phone numbers should start with the ``+`` symbol and the country code.

Ratios and Fees
^^^^^^^^^^^^^^^

.. ts:def:: LibeufinNumber

   type LibeufinNumber = number;

**Note:** this quantity is normally enforced to have at most
two decimal digits.  The reason is to preserve the 2-decimal
digits policy of the `Amount` type, as `LibeufinNumber` is used
to multiply `Amount`. 

Amounts
^^^^^^^

.. ts:def:: Amount

  type Amount = string;

Amounts have the ``$currency:X.Y`` format, where the
fractional part is optional and may contain at most two
digits.

Permissions
^^^^^^^^^^^

This type epresses which permissions for a subject
apply on a resource.

.. ts:def:: LibeufinPermission

  interface LibeufinPermission {
    subjectType: string;
    subjectId: string;
    resourceType: string;
    resourceId: string;
    permissionName: string
  }
Fetch params
^^^^^^^^^^^^

.. _fetch-params:

.. ts:def:: FetchParams

  interface FetchParams {

    // Because transactions are delivered by banks in "batches",
    // then every batch can have different qualities.  This value
    // lets the request specify which type of batch ought to be
    // returned.  Currently, the following two type are supported:
    //
    // 'report': typically includes only non booked transactions.
    // 'statement': typically includes only booked transactions.
    level: "report" | "statement" | "all";

    // This type indicates the time range of the query.
    // It allows the following values:
    //
    // 'latest': retrieves the last transactions from the bank.
    //           If there are older unread transactions, those will *not*
    //           be downloaded.
    //
    // 'all': retrieves all the transactions from the bank,
    //        until the oldest.
    //
    // 'previous-days': currently *not* implemented, it will allow
    //                  the request to download transactions from
    //                  today until N days before.
    //
    // 'since-last': retrieves all the transactions since the last
    //               time one was downloaded.
    //
    rangeType: "latest" | "all" | "previous-days" | "since-last";
  };