pryv 3.0.2 → 3.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pryv",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "Pryv JavaScript library",
   "keywords": [
     "Pryv",

package/src/Service.js

@@ -3,6 +3,8 @@
  * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
  */
 const utils = require('./utils.js');
+const PryvError = require('./lib/PryvError.js');
+const MfaRequiredError = require('./lib/MfaRequiredError.js');
 // Connection is required at the end of this file to allow circular requires.
 const Assets = require('./ServiceAssets.js');
 
@@ -182,20 +184,388 @@ class Service {
     );
 
     if (!response.ok) {
-      if (body?.error?.message) {
-        throw new Error(body.error.message);
-      }
-      throw new Error('Login failed: ' + JSON.stringify(body));
+      throw PryvError.fromApiResponse(response, body);
+    }
+
+    if (body && body.mfaToken) {
+      throw new MfaRequiredError(body.mfaToken, response, body);
     }
 
-    if (!body.token) {
-      throw new Error('Invalid login response: ' + JSON.stringify(body));
+    if (!body || !body.token) {
+      throw new PryvError(
+        'Invalid login response: ' + JSON.stringify(body)
+      );
     }
     return new Connection(
       Service.buildAPIEndpoint(await this.info(), username, body.token),
       this // Pre load Connection with service
     );
   }
+
+  /**
+   * Re-trigger an MFA challenge (e.g. resend SMS) during a pending login.
+   * Use after `login()` threw `MfaRequiredError` if the user needs another
+   * SMS code.
+   *
+   * @param {string} userId
+   * @param {string} mfaToken - From `MfaRequiredError.mfaToken`
+   * @returns {Promise<void>}
+   * @throws {PryvError} on 4xx/5xx (e.g. invalid/expired mfaToken)
+   */
+  async mfaChallenge (userId, mfaToken) {
+    if (!userId || !mfaToken) {
+      throw new PryvError('mfaChallenge requires userId and mfaToken');
+    }
+    const url = await this.apiEndpointFor(userId) + 'mfa/challenge';
+    const { response, body } = await utils.fetchPost(url, {}, {
+      Authorization: mfaToken
+    });
+    if (!response.ok) throw PryvError.fromApiResponse(response, body);
+  }
+
+  /**
+   * Finish an MFA-protected login by submitting the SMS code. Returns a
+   * fully-formed `Connection` (parallel to `Service.login`).
+   *
+   * @param {string} userId
+   * @param {string} mfaToken - From `MfaRequiredError.mfaToken`
+   * @param {string} code - The SMS verification code
+   * @returns {Promise<Connection>}
+   * @throws {PryvError} on bad code, expired mfaToken, etc.
+   */
+  async mfaVerify (userId, mfaToken, code) {
+    if (!userId || !mfaToken || code == null) {
+      throw new PryvError('mfaVerify requires userId, mfaToken, code');
+    }
+    const url = await this.apiEndpointFor(userId) + 'mfa/verify';
+    const { response, body } = await utils.fetchPost(url, { code }, {
+      Authorization: mfaToken
+    });
+    if (!response.ok) throw PryvError.fromApiResponse(response, body);
+    if (!body || !body.token) {
+      throw new PryvError(
+        'mfa.verify did not return a token: ' + JSON.stringify(body)
+      );
+    }
+    return new Connection(
+      Service.buildAPIEndpoint(await this.info(), userId, body.token),
+      this
+    );
+  }
+
+  /**
+   * Check whether a username is registered on this service.
+   * One round-trip via `POST <register>/<userId>/server`.
+   *
+   * @param {string} userId - The username to check
+   * @returns {Promise<boolean>} `true` if registered, `false` on 404
+   * @throws {PryvError} on network errors or non-404 API errors
+   */
+  async userExists (userId) {
+    const serviceInfo = await this.info();
+    const url = serviceInfo.register + encodeURIComponent(userId) + '/server';
+    const { response, body } = await utils.fetchPost(url, {});
+    if (response.ok) return true;
+    if (response.status === 404) return false;
+    throw PryvError.fromApiResponse(response, body);
+  }
+
+  /**
+   * Resolve an email address to a username on this service.
+   * One round-trip via `GET <register>/<email>/uid`.
+   *
+   * @param {string} email - The email to look up
+   * @returns {Promise<string|null>} The username, or `null` if unknown
+   * @throws {PryvError} on network errors or non-404 API errors
+   */
+  async userIdForEmail (email) {
+    const serviceInfo = await this.info();
+    const url = serviceInfo.register + encodeURIComponent(email) + '/uid';
+    const { response, body } = await utils.fetchGet(url);
+    if (response.ok) return (body && (body.uid || body.username)) || null;
+    if (response.status === 404) return null;
+    throw PryvError.fromApiResponse(response, body);
+  }
+
+  /**
+   * Fetch the raw hostings tree advertised by `<register>/hostings`.
+   *
+   * Returns the nested API shape `{ regions: { <region>: { zones:
+   * { <zone>: { hostings: { <key>: { name, description, availableCore,
+   * available } } } } } } }`. For a flat list ready to render in a UI,
+   * use `flatHostings()`.
+   *
+   * @returns {Promise<Object>} the raw `/reg/hostings` body
+   * @throws {PryvError} on non-2xx
+   */
+  async availableHostings () {
+    const serviceInfo = await this.info();
+    const { response, body } = await utils.fetchGet(
+      serviceInfo.register + 'hostings'
+    );
+    if (!response.ok) throw PryvError.fromApiResponse(response, body);
+    return body;
+  }
+
+  /**
+   * Flatten `availableHostings()` into a list of `{ key, name, description,
+   * region, zone, availableCore, available }` items.
+   *
+   * @returns {Promise<Array<Object>>}
+   * @throws {PryvError} on non-2xx
+   */
+  async flatHostings () {
+    const tree = await this.availableHostings();
+    const out = [];
+    const regions = (tree && tree.regions) || {};
+    for (const [regionKey, region] of Object.entries(regions)) {
+      const zones = (region && region.zones) || {};
+      for (const [zoneKey, zone] of Object.entries(zones)) {
+        const hostings = (zone && zone.hostings) || {};
+        for (const [key, h] of Object.entries(hostings)) {
+          if (!h) continue;
+          out.push({
+            key,
+            name: h.name,
+            description: h.description,
+            region: regionKey,
+            zone: zoneKey,
+            availableCore: h.availableCore,
+            available: h.available === true
+          });
+        }
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Register a new user on this service.
+   *
+   * Hides the v1/v2 register endpoint difference. v2 platforms (service
+   * version >= 2.0 or >= 1.6) accept camelCase fields at `<register>users`;
+   * older v1 service-register expects mixed-case fields at `<register>user`.
+   *
+   * Pass `hosting: 'auto'` to use the first hosting flagged `available: true`
+   * in `flatHostings()` — useful for tests and single-hosting platforms.
+   *
+   * @param {Object} opts
+   * @param {string} opts.username
+   * @param {string} opts.password
+   * @param {string} opts.email
+   * @param {string} opts.hosting - Hosting key (use `service.flatHostings()` to discover) or `'auto'`
+   * @param {string} opts.appId
+   * @param {string} [opts.language='en']
+   * @param {string} [opts.invitationToken='enjoy']
+   * @param {string} [opts.referer]
+   * @returns {Promise<{ username: string, apiEndpoint: string }>}
+   * @throws {PryvError} on duplicate username, weak password, etc.
+   */
+  async createUser (opts) {
+    if (!opts || !opts.username || !opts.password || !opts.email ||
+        !opts.hosting || !opts.appId) {
+      throw new PryvError(
+        'createUser requires username, password, email, hosting, appId'
+      );
+    }
+    const serviceInfo = await this.info();
+    const isModern = supportsCamelCaseRegister(serviceInfo.version);
+    const language = opts.language || 'en';
+    const invitationToken = opts.invitationToken || 'enjoy';
+
+    let hosting = opts.hosting;
+    if (hosting === 'auto') {
+      const flat = await this.flatHostings();
+      const first = flat.find(h => h.available);
+      if (!first) {
+        throw new PryvError(
+          'createUser({ hosting: "auto" }): no hosting flagged available'
+        );
+      }
+      hosting = first.key;
+    }
+
+    let url, payload;
+    if (isModern) {
+      url = serviceInfo.register + 'users';
+      payload = {
+        appId: opts.appId,
+        username: opts.username,
+        password: opts.password,
+        email: opts.email,
+        hosting,
+        language,
+        invitationToken
+      };
+      if (opts.referer != null) payload.referer = opts.referer;
+    } else {
+      url = serviceInfo.register + 'user';
+      payload = {
+        appid: opts.appId,
+        username: opts.username,
+        password: opts.password,
+        email: opts.email,
+        hosting,
+        languageCode: language,
+        invitationtoken: invitationToken
+      };
+      if (opts.referer != null) payload.referer = opts.referer;
+    }
+    const { response, body } = await utils.fetchPost(url, payload);
+    if (!response.ok) throw PryvError.fromApiResponse(response, body);
+    const apiEndpoint = await this.apiEndpointFor(opts.username);
+    return { username: opts.username, apiEndpoint };
+  }
+
+  /**
+   * Trigger a password-reset email for the given user.
+   * Pre-auth — no token required.
+   *
+   * @param {string} userId
+   * @param {string} appId
+   * @returns {Promise<void>}
+   * @throws {PryvError} on 4xx/5xx
+   */
+  async requestPasswordReset (userId, appId) {
+    if (!userId || !appId) {
+      throw new PryvError('requestPasswordReset requires userId and appId');
+    }
+    const url = await this.apiEndpointFor(userId) +
+      'account/request-password-reset';
+    const { response, body } = await utils.fetchPost(url, {
+      appId,
+      username: userId
+    });
+    if (!response.ok) throw PryvError.fromApiResponse(response, body);
+  }
+
+  /**
+   * Start an access-request flow. Posts to the platform's auth endpoint
+   * (`serviceInfo.access`) and returns the envelope the consumer needs to
+   * present an approve-link to the user and poll for completion.
+   *
+   * `Browser.setupAuth` already wraps this for the high-level browser flow.
+   * Use this method when you're a non-browser caller (CLI, native app, bot)
+   * or building your own UI on top.
+   *
+   * @param {Object} authRequest - The auth-request body
+   * @param {string} authRequest.requestingAppId
+   * @param {Array<{ streamId: string, level: string, defaultName: string }>} authRequest.requestedPermissions
+   * @param {string} [authRequest.languageCode='en']
+   * @param {string|boolean} [authRequest.returnUrl]
+   * @param {string} [authRequest.referer]
+   * @param {Object} [authRequest.clientData]
+   * @param {string} [authRequest.deviceName]
+   * @param {number} [authRequest.expireAfter]
+   * @returns {Promise<{ key: string, authUrl: string, poll: string, pollRateMs: number }>}
+   * @throws {PryvError} on non-2xx
+   */
+  async startAccessRequest (authRequest) {
+    if (!authRequest || !authRequest.requestingAppId) {
+      throw new PryvError(
+        'startAccessRequest requires authRequest.requestingAppId'
+      );
+    }
+    const serviceInfo = await this.info();
+    const { response, body } = await utils.fetchPost(
+      serviceInfo.access,
+      authRequest
+    );
+    if (!response.ok) throw PryvError.fromApiResponse(response, body);
+    if (!body || !body.key || !body.poll) {
+      throw new PryvError(
+        'Invalid access-request response: ' + JSON.stringify(body)
+      );
+    }
+    return {
+      key: body.key,
+      authUrl: body.authUrl || body.url,
+      poll: body.poll,
+      pollRateMs: body.poll_rate_ms != null ? body.poll_rate_ms : body.pollRateMs
+    };
+  }
+
+  /**
+   * Poll an in-progress access request once. Accepts either:
+   *   - a `key` returned by `startAccessRequest` (poll URL is built from
+   *     `serviceInfo.access + key`)
+   *   - a full poll URL (use as-is — recommended, since the server-issued
+   *     URL is canonical and may include a different subdomain).
+   *
+   * Returns the raw body. Inspect `body.status` to drive the flow:
+   *   - `'NEED_SIGNIN'` → user has not interacted yet; keep polling.
+   *   - `'ACCEPTED'`    → `body.apiEndpoint` + `body.username` + `body.token` are set.
+   *   - `'REFUSED'`     → user declined.
+   *
+   * @param {string} keyOrPollUrl
+   * @returns {Promise<Object>}
+   * @throws {PryvError} on transport errors or non-2xx-and-not-403-REFUSED
+   */
+  async pollAccessRequest (keyOrPollUrl) {
+    if (!keyOrPollUrl) {
+      throw new PryvError('pollAccessRequest requires a key or poll URL');
+    }
+    let pollUrl = keyOrPollUrl;
+    if (!/^https?:\/\//.test(keyOrPollUrl)) {
+      const serviceInfo = await this.info();
+      pollUrl = serviceInfo.access + keyOrPollUrl;
+    }
+    const { response, body } = await utils.fetchGet(pollUrl);
+    // 403 with status=REFUSED is the canonical "user declined" terminal
+    // state — treat as a successful poll, not an error (matches the
+    // behaviour of `Auth/AuthController.js`).
+    if (response.status === 403 && body && body.status === 'REFUSED') {
+      return body;
+    }
+    if (!response.ok) throw PryvError.fromApiResponse(response, body);
+    return body;
+  }
+
+  /**
+   * Set a new password using a reset token (from the reset email).
+   * Pre-auth — no login token required.
+   *
+   * @param {string} userId
+   * @param {string} newPassword
+   * @param {string} resetToken
+   * @param {string} appId
+   * @returns {Promise<void>}
+   * @throws {PryvError} on `unknown-or-expired-reset-token`, weak password, etc.
+   */
+  async resetPassword (userId, newPassword, resetToken, appId) {
+    if (!userId || !newPassword || !resetToken || !appId) {
+      throw new PryvError(
+        'resetPassword requires userId, newPassword, resetToken, appId'
+      );
+    }
+    const url = await this.apiEndpointFor(userId) + 'account/reset-password';
+    const { response, body } = await utils.fetchPost(url, {
+      username: userId,
+      newPassword,
+      resetToken,
+      appId
+    });
+    if (!response.ok) throw PryvError.fromApiResponse(response, body);
+  }
+}
+
+/**
+ * Detect whether the platform's service-info `version` supports the modern
+ * camelCase register endpoint (`POST /users`). v2 service-register routes
+ * both, but v1 platforms only accept the mixed-case `POST /user`.
+ *
+ * @param {string|undefined} version - service-info `version` field
+ * @returns {boolean}
+ */
+function supportsCamelCaseRegister (version) {
+  if (!version || typeof version !== 'string') return true; // optimistic: assume v2+
+  const m = /^(\d+)\.(\d+)/.exec(version);
+  if (!m) return true;
+  const major = parseInt(m[1], 10);
+  const minor = parseInt(m[2], 10);
+  if (major >= 2) return true;
+  if (major === 1 && minor >= 6) return true;
+  return false;
 }
 
 module.exports = Service;

package/src/index.d.ts

@@ -166,14 +166,101 @@ declare module 'pryv' {
 
   /**
    * Custom error class for Pryv library errors.
-   * Includes an innerObject property for wrapping underlying errors.
+   *
+   * - `innerObject`: legacy field, set by the 2-arg constructor.
+   * - `id` / `status` / `response`: structured fields populated by
+   *   `PryvError.fromApiResponse(response, body)` for errors that came
+   *   from a Pryv API call. All three are `undefined` for legacy errors.
    */
   export class PryvError extends globalThis.Error {
     constructor(message: string, innerObject?: globalThis.Error | object);
     name: 'PryvError';
     innerObject?: globalThis.Error | object;
+    id?: string;
+    status?: number;
+    response?: { body: any; status: number };
+    static fromApiResponse(response: Response, body?: any): PryvError;
   }
 
+  /**
+   * Thrown by `Service.login` when the platform returned `{ mfaToken }`
+   * instead of `{ token }`. Carries the `mfaToken` so the consumer can
+   * call `Service.mfaVerify(userId, err.mfaToken, code)` after prompting
+   * the user for their SMS code.
+   */
+  export class MfaRequiredError extends PryvError {
+    constructor(mfaToken: string, response: Response, body?: any);
+    name: 'MfaRequiredError';
+    mfaToken: string;
+  }
+
+  /** Catalogue of Pryv API error ids (mirrors open-pryv.io ErrorIds.js). */
+  export const ERRORS: {
+    readonly API_UNAVAILABLE: 'api-unavailable';
+    readonly CORRUPTED_DATA: 'corrupted-data';
+    readonly FORBIDDEN: 'forbidden';
+    readonly INVALID_ACCESS_TOKEN: 'invalid-access-token';
+    readonly INVALID_CREDENTIALS: 'invalid-credentials';
+    readonly UNSUPPORTED_OPERATION: 'unsupported-operation';
+    readonly INVALID_EVENT_TYPE: 'invalid-event-type';
+    readonly INVALID_ITEM_ID: 'invalid-item-id';
+    readonly INVALID_METHOD: 'invalid-method';
+    readonly INVALID_OPERATION: 'invalid-operation';
+    readonly INVALID_PARAMETERS_FORMAT: 'invalid-parameters-format';
+    readonly INVALID_REQUEST_STRUCTURE: 'invalid-request-structure';
+    readonly ITEM_ALREADY_EXISTS: 'item-already-exists';
+    readonly MISSING_HEADER: 'missing-header';
+    readonly UNEXPECTED_ERROR: 'unexpected-error';
+    readonly UNKNOWN_REFERENCED_RESOURCE: 'unknown-referenced-resource';
+    readonly UNKNOWN_RESOURCE: 'unknown-resource';
+    readonly UNSUPPORTED_CONTENT_TYPE: 'unsupported-content-type';
+    readonly TOO_MANY_RESULTS: 'too-many-results';
+    readonly GONE: 'removed-method';
+    readonly UNAVAILABLE_METHOD: 'unavailable-method';
+    readonly INVALID_INVITATION_TOKEN: 'invitationToken-invalid';
+    readonly INVALID_USERNAME: 'username-invalid';
+    readonly USERNAME_REQUIRED: 'username-required';
+    readonly INVALID_EMAIL: 'email-invalid';
+    readonly INVALID_LANGUAGE: 'language-invalid';
+    readonly INVALID_APP_ID: 'appid-invalid';
+    readonly INVALID_PASSWORD: 'password-invalid';
+    readonly INVALID_REFERER: 'referer-invalid';
+    readonly EMAIL_REQUIRED: 'email-required';
+    readonly PASSWORD_REQUIRED: 'password-required';
+    readonly MISSING_REQUIRED_FIELD: 'missing-required-field';
+    readonly NEW_PASSWORD_FIELD_IS_REQUIRED: 'newPassword-required';
+    readonly DENIED_STREAM_ACCESS: 'denied-stream-access';
+    readonly TOO_HIGH_ACCESS_FOR_SYSTEM_STREAMS: 'too-high-access-for-account-stream';
+    readonly FORBIDDEN_MULTIPLE_ACCOUNT_STREAMS: 'forbidden-multiple-account-streams-events';
+    readonly FORBIDDEN_ACCOUNT_EVENT_MODIFICATION: 'forbidden-none-editable-account-streams';
+    readonly FORBIDDEN_TO_CHANGE_ACCOUNT_STREAM_ID: 'forbidden-change-account-streams-id';
+    readonly FORBIDDEN_TO_EDIT_NONEDITABLE_ACCOUNT_FIELDS: 'forbidden-to-edit-noneditable-account-fields';
+    readonly UNKNOWN_USER: 'unknown-user';
+    readonly UNKNOWN_EMAIL: 'unknown-email';
+  };
+
+  export type CreateUserOptions = {
+    username: string;
+    password: string;
+    email: string;
+    /** Hosting key (from `flatHostings()`) or the literal `'auto'` */
+    hosting: string;
+    appId: string;
+    language?: string;
+    invitationToken?: string;
+    referer?: string;
+  };
+
+  export type HostingItem = {
+    key: string;
+    name: string;
+    description: string;
+    region: string;
+    zone: string;
+    availableCore: string;
+    available: boolean;
+  };
+
   export type StreamsQuery = {
     any?: Identifier[];
     all?: Identifier[];
@@ -736,6 +823,24 @@ declare module 'pryv' {
     supportsHF(): Promise<boolean>;
     isDnsLess(): Promise<boolean>;
 
+    userExists(userId: string): Promise<boolean>;
+    userIdForEmail(email: string): Promise<string | null>;
+    availableHostings(): Promise<any>;
+    flatHostings(): Promise<HostingItem[]>;
+    createUser(opts: CreateUserOptions): Promise<{ username: string; apiEndpoint: string }>;
+    requestPasswordReset(userId: string, appId: string): Promise<void>;
+    resetPassword(userId: string, newPassword: string, resetToken: string, appId: string): Promise<void>;
+    mfaChallenge(userId: string, mfaToken: string): Promise<void>;
+    mfaVerify(userId: string, mfaToken: string, code: string): Promise<Connection>;
+
+    startAccessRequest(authRequest: AuthSettings['authRequest']): Promise<{
+      key: string;
+      authUrl: string;
+      poll: string;
+      pollRateMs: number;
+    }>;
+    pollAccessRequest(keyOrPollUrl: string): Promise<any>;
+
     static buildAPIEndpoint(
       serviceInfo: ServiceInfo,
       username: string,
@@ -1002,6 +1107,8 @@ declare module 'pryv' {
       getQueryParamsFromURL(url: string): KeyValue;
     };
     PryvError: typeof PryvError;
+    MfaRequiredError: typeof MfaRequiredError;
+    ERRORS: typeof ERRORS;
     version: version;
   };
 

package/src/index.js

@@ -9,7 +9,8 @@
  * @property {pryv.Connection} Connection - To interact with an individual's (user) data set
  * @property {pryv.Browser} Browser - Browser Tools - Access request helpers and visuals (button)
  * @property {pryv.utils} utils - Exposes some utils for HTTP calls and tools to manipulate Pryv's API endpoints
- * @property {pryv.PryvError} PryvError - Custom error class with innerObject support
+ * @property {pryv.PryvError} PryvError - Custom error class with innerObject + structured API-error fields
+ * @property {Object} ERRORS - Catalogue of Pryv API error ids (mirrors open-pryv.io/components/errors)
  */
 module.exports = {
   Service: require('./Service'),
@@ -18,5 +19,7 @@ module.exports = {
   Browser: require('./Browser'),
   utils: require('./utils'),
   PryvError: require('./lib/PryvError'),
+  MfaRequiredError: require('./lib/MfaRequiredError'),
+  ERRORS: require('./lib/errorIds'),
   version: require('../package.json').version
 };

package/src/lib/MfaRequiredError.js

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+
+const PryvError = require('./PryvError');
+
+/**
+ * Thrown by `Service.login` when the platform replied with `{ mfaToken }`
+ * instead of `{ token }`. Consumers catch this, prompt the user for the
+ * SMS code, then call `Service.mfaVerify(userId, err.mfaToken, code)`.
+ *
+ *   try { conn = await service.login(u, p, app) }
+ *   catch (err) {
+ *     if (err instanceof MfaRequiredError) {
+ *       const code = await prompt()
+ *       conn = await service.mfaVerify(u, err.mfaToken, code)
+ *     } else { throw err }
+ *   }
+ *
+ * @extends PryvError
+ */
+class MfaRequiredError extends PryvError {
+  /**
+   * @param {string} mfaToken - The token returned by the API (use with mfa.challenge / mfa.verify)
+   * @param {Response} response - The fetch Response object
+   * @param {Object} [body] - Parsed JSON body
+   */
+  constructor (mfaToken, response, body) {
+    const apiErr = body && body.error;
+    const message = (apiErr && apiErr.message) || 'MFA required';
+    super(message);
+    this.name = 'MfaRequiredError';
+    /** @type {string} */
+    this.mfaToken = mfaToken;
+    this.id = (apiErr && apiErr.id) || 'mfa-required';
+    this.status = response && response.status;
+    this.response = { body, status: response && response.status };
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, MfaRequiredError);
+    }
+  }
+}
+
+module.exports = MfaRequiredError;

package/src/lib/PryvError.js

@@ -5,26 +5,60 @@
 
 /**
  * Custom error class for Pryv library errors.
- * Includes an innerObject property for wrapping underlying errors.
+ *
+ * Two construction patterns are supported (additive — both stay valid):
+ *
+ *   // Legacy: wrap an underlying error or value
+ *   throw new PryvError('Failed to do X', innerError)
+ *
+ *   // Structured: carry the API error id, HTTP status, and raw response
+ *   throw PryvError.fromApiResponse(response, body)
+ *
+ * Structured fields (`id`, `status`, `response`) are `undefined` unless set
+ * via the static factory or assigned post-hoc.
+ *
  * @extends Error
  */
 class PryvError extends Error {
   /**
-   * Create a PryvError
    * @param {string} message - Error message
-   * @param {Error|Object} [innerObject] - The underlying error or object that caused this error
+   * @param {Error|Object} [innerObject] - Underlying error or value
    */
   constructor (message, innerObject) {
     super(message);
     this.name = 'PryvError';
     /** @type {Error|Object|undefined} */
     this.innerObject = innerObject;
+    /** @type {string|undefined} Pryv API error id, e.g. `'unknown-user'` */
+    this.id = undefined;
+    /** @type {number|undefined} HTTP status that produced this error */
+    this.status = undefined;
+    /** @type {{ body: any, status: number }|undefined} Raw response */
+    this.response = undefined;
 
-    // Maintains proper stack trace for where error was thrown (only in V8)
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, PryvError);
     }
   }
+
+  /**
+   * Build a PryvError from a fetch Response and its parsed JSON body.
+   * Pulls `id` and `message` from `body.error` when present (Pryv API shape).
+   *
+   * @param {Response} response - The fetch Response object
+   * @param {Object} [body] - Parsed JSON body
+   * @returns {PryvError}
+   */
+  static fromApiResponse (response, body) {
+    const apiErr = body && body.error;
+    const message = (apiErr && apiErr.message) ||
+      `Pryv API error (HTTP ${response.status})`;
+    const err = new PryvError(message);
+    err.id = apiErr && apiErr.id;
+    err.status = response.status;
+    err.response = { body, status: response.status };
+    return err;
+  }
 }
 
 module.exports = PryvError;

package/src/lib/errorIds.js

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+
+/**
+ * Catalogue of Pryv API error ids.
+ *
+ * Mirrors `open-pryv.io/components/errors/src/ErrorIds.js`. Use these
+ * constants instead of hardcoding error-id strings:
+ *
+ *   if (err instanceof PryvError && err.id === pryv.ERRORS.UNKNOWN_USER) { … }
+ *
+ * Adding a new id here is safe; renaming or removing one is a breaking
+ * change for consumers using the constant.
+ */
+const ERRORS = Object.freeze({
+  API_UNAVAILABLE: 'api-unavailable',
+  CORRUPTED_DATA: 'corrupted-data',
+  FORBIDDEN: 'forbidden',
+  INVALID_ACCESS_TOKEN: 'invalid-access-token',
+  INVALID_CREDENTIALS: 'invalid-credentials',
+  UNSUPPORTED_OPERATION: 'unsupported-operation',
+  INVALID_EVENT_TYPE: 'invalid-event-type',
+  INVALID_ITEM_ID: 'invalid-item-id',
+  INVALID_METHOD: 'invalid-method',
+  INVALID_OPERATION: 'invalid-operation',
+  INVALID_PARAMETERS_FORMAT: 'invalid-parameters-format',
+  INVALID_REQUEST_STRUCTURE: 'invalid-request-structure',
+  ITEM_ALREADY_EXISTS: 'item-already-exists',
+  MISSING_HEADER: 'missing-header',
+  UNEXPECTED_ERROR: 'unexpected-error',
+  UNKNOWN_REFERENCED_RESOURCE: 'unknown-referenced-resource',
+  UNKNOWN_RESOURCE: 'unknown-resource',
+  UNSUPPORTED_CONTENT_TYPE: 'unsupported-content-type',
+  TOO_MANY_RESULTS: 'too-many-results',
+  GONE: 'removed-method',
+  UNAVAILABLE_METHOD: 'unavailable-method',
+
+  // Registration / unique-field validation
+  INVALID_INVITATION_TOKEN: 'invitationToken-invalid',
+  INVALID_USERNAME: 'username-invalid',
+  USERNAME_REQUIRED: 'username-required',
+  INVALID_EMAIL: 'email-invalid',
+  INVALID_LANGUAGE: 'language-invalid',
+  INVALID_APP_ID: 'appid-invalid',
+  INVALID_PASSWORD: 'password-invalid',
+  INVALID_REFERER: 'referer-invalid',
+  EMAIL_REQUIRED: 'email-required',
+  PASSWORD_REQUIRED: 'password-required',
+  MISSING_REQUIRED_FIELD: 'missing-required-field',
+  NEW_PASSWORD_FIELD_IS_REQUIRED: 'newPassword-required',
+
+  // Account-stream / system-stream protections
+  DENIED_STREAM_ACCESS: 'denied-stream-access',
+  TOO_HIGH_ACCESS_FOR_SYSTEM_STREAMS: 'too-high-access-for-account-stream',
+  FORBIDDEN_MULTIPLE_ACCOUNT_STREAMS: 'forbidden-multiple-account-streams-events',
+  FORBIDDEN_ACCOUNT_EVENT_MODIFICATION: 'forbidden-none-editable-account-streams',
+  FORBIDDEN_TO_CHANGE_ACCOUNT_STREAM_ID: 'forbidden-change-account-streams-id',
+  FORBIDDEN_TO_EDIT_NONEDITABLE_ACCOUNT_FIELDS: 'forbidden-to-edit-noneditable-account-fields',
+
+  // Pre-auth lookups (returned by `/reg/:email/uid` and similar)
+  UNKNOWN_USER: 'unknown-user',
+  UNKNOWN_EMAIL: 'unknown-email'
+});
+
+module.exports = ERRORS;

package/test/PryvError.test.js

@@ -37,4 +37,38 @@ describe('[PERX] PryvError', function () {
     const error = new PryvError('No inner');
     expect(error.innerObject).to.be.undefined;
   });
+
+  it('[PERF] structured fields default to undefined for legacy constructor', function () {
+    const error = new PryvError('Test');
+    expect(error.id).to.be.undefined;
+    expect(error.status).to.be.undefined;
+    expect(error.response).to.be.undefined;
+  });
+
+  it('[PERG] fromApiResponse populates id/status/response from API body', function () {
+    const fakeResponse = { status: 404 };
+    const body = { error: { id: 'unknown-user', message: 'Unknown user' } };
+    const error = PryvError.fromApiResponse(fakeResponse, body);
+    expect(error).to.be.instanceOf(PryvError);
+    expect(error.id).to.equal('unknown-user');
+    expect(error.status).to.equal(404);
+    expect(error.response).to.deep.equal({ body, status: 404 });
+    expect(error.message).to.equal('Unknown user');
+    expect(error.innerObject).to.be.undefined;
+  });
+
+  it('[PERH] fromApiResponse falls back to a generic message when body has no error', function () {
+    const fakeResponse = { status: 500 };
+    const error = PryvError.fromApiResponse(fakeResponse, { foo: 'bar' });
+    expect(error.id).to.be.undefined;
+    expect(error.status).to.equal(500);
+    expect(error.message).to.match(/HTTP 500/);
+  });
+
+  it('[PERI] fromApiResponse handles null/undefined body without throwing', function () {
+    const fakeResponse = { status: 502 };
+    const error = PryvError.fromApiResponse(fakeResponse, undefined);
+    expect(error.status).to.equal(502);
+    expect(error.response).to.deep.equal({ body: undefined, status: 502 });
+  });
 });

package/test/Service.accessRequest.test.js

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, before, expect, pryv, testData */
+
+describe('[ARQX] Service access-request init', function () {
+  let service;
+
+  before(async function () {
+    this.timeout(15000);
+    await testData.prepare();
+    service = new pryv.Service(testData.serviceInfoUrl);
+  });
+
+  describe('[ASTX] Service.startAccessRequest', function () {
+    it('[ASTA] rejects when requestingAppId is missing', async function () {
+      let caught;
+      try { await service.startAccessRequest({}); } catch (e) { caught = e; }
+      expect(caught).to.be.instanceOf(pryv.PryvError);
+    });
+
+    it('[ASTB] returns { key, authUrl, poll, pollRateMs }', async function () {
+      this.timeout(15000);
+      const env = await service.startAccessRequest({
+        requestingAppId: 'jslib-test',
+        requestedPermissions: [{
+          streamId: 'data',
+          level: 'read',
+          defaultName: 'Test'
+        }]
+      });
+      expect(env.key).to.be.a('string');
+      expect(env.authUrl).to.be.a('string');
+      expect(env.poll).to.be.a('string');
+      expect(env.poll).to.match(/^https?:\/\//);
+      expect(env.pollRateMs).to.be.a('number');
+    });
+  });
+
+  describe('[APRX] Service.pollAccessRequest', function () {
+    it('[APRA] rejects when key is missing', async function () {
+      let caught;
+      try { await service.pollAccessRequest(); } catch (e) { caught = e; }
+      expect(caught).to.be.instanceOf(pryv.PryvError);
+    });
+
+    it('[APRB] polling a fresh request returns NEED_SIGNIN', async function () {
+      this.timeout(15000);
+      const env = await service.startAccessRequest({
+        requestingAppId: 'jslib-test',
+        requestedPermissions: [{
+          streamId: 'data',
+          level: 'read',
+          defaultName: 'Test'
+        }]
+      });
+      const state = await service.pollAccessRequest(env.poll);
+      expect(state).to.exist;
+      expect(state.status).to.equal('NEED_SIGNIN');
+    });
+
+    it('[APRC] accepts a bare key (no scheme) and builds the URL', async function () {
+      this.timeout(15000);
+      const env = await service.startAccessRequest({
+        requestingAppId: 'jslib-test',
+        requestedPermissions: [{
+          streamId: 'data',
+          level: 'read',
+          defaultName: 'Test'
+        }]
+      });
+      const state = await service.pollAccessRequest(env.key);
+      expect(state).to.exist;
+      expect(state.status).to.equal('NEED_SIGNIN');
+    });
+  });
+});

package/test/Service.createUser.test.js

@@ -0,0 +1,104 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, before, expect, pryv, testData */
+
+const { createId: cuid } = require('@paralleldrive/cuid2');
+
+describe('[CRUX] Service.createUser', function () {
+  let service;
+  let hostingKey;
+
+  before(async function () {
+    this.timeout(15000);
+    await testData.prepare();
+    service = new pryv.Service(testData.serviceInfoUrl);
+    const serviceInfo = await service.info();
+    // Discover any available hosting key — equivalent to what the deferred
+    // 1.4 `flatHostings()` will eventually do.
+    const res = await fetch(serviceInfo.register + 'hostings');
+    const tree = await res.json();
+    hostingKey = findFirstAvailableHostingKey(tree);
+    if (!hostingKey) this.skip();
+  });
+
+  it('[CRUA] rejects when required fields are missing', async function () {
+    let caught;
+    try {
+      await service.createUser({ username: 'foo' });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).to.be.instanceOf(pryv.PryvError);
+    expect(caught.message).to.match(/createUser requires/);
+  });
+
+  it('[CRUB] creates a fresh user and returns username + apiEndpoint', async function () {
+    this.timeout(20000);
+    const username = 'jslibcr' + cuid().slice(0, 8);
+    const result = await service.createUser({
+      username,
+      password: username + 'PASS!1',
+      email: username + '@example.com',
+      hosting: hostingKey,
+      appId: 'jslib-test',
+      language: 'en'
+    });
+    expect(result.username).to.equal(username);
+    expect(result.apiEndpoint).to.be.a('string');
+    expect(result.apiEndpoint).to.include(username);
+
+    // Sanity: the new user can be looked up
+    const exists = await service.userExists(username);
+    expect(exists).to.equal(true);
+  });
+
+  it('[CRUC] throws PryvError when re-creating an existing user', async function () {
+    this.timeout(20000);
+    let caught;
+    try {
+      await service.createUser({
+        username: testData.username,
+        password: testData.password,
+        email: testData.username + '@pryv.io',
+        hosting: hostingKey,
+        appId: 'jslib-test'
+      });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).to.be.instanceOf(pryv.PryvError);
+    expect(caught.status).to.be.gte(400);
+    // Server-side validation order varies; we don't pin the exact id.
+    expect(caught.response).to.have.property('status');
+  });
+
+  it('[CRUD] hosting: "auto" picks the first available hosting', async function () {
+    this.timeout(20000);
+    const username = 'jsliba' + cuid().slice(0, 8);
+    const result = await service.createUser({
+      username,
+      password: username + 'PASS!1',
+      email: username + '@example.com',
+      hosting: 'auto',
+      appId: 'jslib-test'
+    });
+    expect(result.username).to.equal(username);
+    expect(result.apiEndpoint).to.be.a('string');
+  });
+});
+
+function findFirstAvailableHostingKey (tree) {
+  const regions = (tree && tree.regions) || {};
+  for (const region of Object.values(regions)) {
+    const zones = region.zones || {};
+    for (const zone of Object.values(zones)) {
+      const hostings = zone.hostings || {};
+      for (const [key, h] of Object.entries(hostings)) {
+        if (h && h.available) return key;
+      }
+    }
+  }
+  return null;
+}

package/test/Service.hostings.test.js

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, before, expect, pryv, testData */
+
+describe('[HSTX] Service.availableHostings + flatHostings', function () {
+  let service;
+
+  before(async function () {
+    this.timeout(15000);
+    await testData.prepare();
+    service = new pryv.Service(testData.serviceInfoUrl);
+  });
+
+  it('[HSTA] availableHostings() returns the raw regions tree', async function () {
+    this.timeout(15000);
+    const tree = await service.availableHostings();
+    expect(tree).to.be.an('object');
+    expect(tree.regions).to.be.an('object');
+    // At least one region with at least one zone with at least one hosting
+    const regions = Object.values(tree.regions);
+    expect(regions.length).to.be.gte(1);
+  });
+
+  it('[HSTB] flatHostings() returns a list with key/name/region/zone fields', async function () {
+    this.timeout(15000);
+    const list = await service.flatHostings();
+    expect(list).to.be.an('array');
+    expect(list.length).to.be.gte(1);
+    for (const item of list) {
+      expect(item.key).to.be.a('string');
+      expect(item.name).to.be.a('string');
+      expect(item.region).to.be.a('string');
+      expect(item.zone).to.be.a('string');
+      expect(item.availableCore).to.be.a('string');
+      expect(item.available).to.be.a('boolean');
+    }
+  });
+
+  it('[HSTC] flatHostings() shape matches availableHostings() leaf nodes', async function () {
+    this.timeout(15000);
+    const tree = await service.availableHostings();
+    const flat = await service.flatHostings();
+    let leafCount = 0;
+    for (const region of Object.values(tree.regions || {})) {
+      for (const zone of Object.values(region.zones || {})) {
+        leafCount += Object.keys(zone.hostings || {}).length;
+      }
+    }
+    expect(flat.length).to.equal(leafCount);
+  });
+});

package/test/Service.mfa.test.js

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, before, expect, pryv, testData */
+
+const { createId: cuid } = require('@paralleldrive/cuid2');
+
+// Note: testData.username is a non-MFA-protected test user, so we cannot
+// exercise the success paths of mfaChallenge / mfaVerify against pryv.me.
+// What we can verify:
+//   - argument validation
+//   - bogus mfaToken → PryvError on the wire
+//   - MfaRequiredError type + export shape
+// The happy path is exercised end-to-end by open-pryv.io's MFA test suite
+// (which spins up a fake SMS provider); replicating that here would require
+// a mock layer the project doesn't ship.
+
+describe('[MFLX] Service MFA', function () {
+  let service;
+
+  before(async function () {
+    this.timeout(15000);
+    await testData.prepare();
+    service = new pryv.Service(testData.serviceInfoUrl);
+  });
+
+  describe('[MCHX] Service.mfaChallenge', function () {
+    it('[MCHA] rejects when args are missing', async function () {
+      let caught;
+      try { await service.mfaChallenge(testData.username); } catch (e) { caught = e; }
+      expect(caught).to.be.instanceOf(pryv.PryvError);
+    });
+
+    it('[MCHB] throws PryvError on bogus mfaToken', async function () {
+      this.timeout(15000);
+      let caught;
+      try {
+        await service.mfaChallenge(testData.username, 'bogus-' + cuid().slice(0, 8));
+      } catch (e) { caught = e; }
+      expect(caught).to.be.instanceOf(pryv.PryvError);
+      expect(caught.status).to.be.gte(400);
+    });
+  });
+
+  describe('[MVRX] Service.mfaVerify', function () {
+    it('[MVRA] rejects when args are missing', async function () {
+      let caught;
+      try { await service.mfaVerify(testData.username, 'token'); } catch (e) { caught = e; }
+      expect(caught).to.be.instanceOf(pryv.PryvError);
+    });
+
+    it('[MVRB] throws PryvError on bogus mfaToken', async function () {
+      this.timeout(15000);
+      let caught;
+      try {
+        await service.mfaVerify(
+          testData.username,
+          'bogus-' + cuid().slice(0, 8),
+          '123456'
+        );
+      } catch (e) { caught = e; }
+      expect(caught).to.be.instanceOf(pryv.PryvError);
+      expect(caught.status).to.be.gte(400);
+    });
+  });
+
+  describe('[MERX] MfaRequiredError', function () {
+    it('[MERA] is exported on the package root and extends PryvError', function () {
+      expect(pryv.MfaRequiredError).to.be.a('function');
+      const err = new pryv.MfaRequiredError(
+        'tok-abc',
+        { status: 200 },
+        { mfaToken: 'tok-abc' }
+      );
+      expect(err).to.be.instanceOf(pryv.MfaRequiredError);
+      expect(err).to.be.instanceOf(pryv.PryvError);
+      expect(err.mfaToken).to.equal('tok-abc');
+      expect(err.id).to.equal('mfa-required');
+      expect(err.status).to.equal(200);
+      expect(err.name).to.equal('MfaRequiredError');
+    });
+
+    it('[MERB] picks up id/message from API error body when provided', function () {
+      const err = new pryv.MfaRequiredError(
+        'tok-xyz',
+        { status: 401 },
+        { error: { id: 'custom-id', message: 'custom msg' } }
+      );
+      expect(err.id).to.equal('custom-id');
+      expect(err.message).to.equal('custom msg');
+    });
+  });
+});

package/test/Service.passwordReset.test.js

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, before, expect, pryv, testData */
+
+const { createId: cuid } = require('@paralleldrive/cuid2');
+
+describe('[PWRX] Service.requestPasswordReset', function () {
+  let service;
+
+  before(async function () {
+    this.timeout(15000);
+    await testData.prepare();
+    service = new pryv.Service(testData.serviceInfoUrl);
+  });
+
+  it('[PWRA] rejects when required args are missing', async function () {
+    let caught;
+    try {
+      await service.requestPasswordReset(testData.username);
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).to.be.instanceOf(pryv.PryvError);
+  });
+
+  it('[PWRB] either resolves or throws PryvError (server may require trusted appId)', async function () {
+    this.timeout(15000);
+    // Pryv platforms typically restrict password-reset to a trusted-appId
+    // allowlist (pryv.me does). On a permissive deployment this resolves;
+    // on a stricter one we expect a structured PryvError, not a raw throw.
+    let caught;
+    try {
+      await service.requestPasswordReset(testData.username, 'jslib-test');
+    } catch (e) {
+      caught = e;
+    }
+    if (caught) {
+      expect(caught).to.be.instanceOf(pryv.PryvError);
+      expect(caught.status).to.be.gte(400);
+    }
+  });
+  // Note: a "user does not exist" path can't be exercised against pryv.me
+  // because per-user DNS doesn't resolve for unregistered usernames — fetch
+  // throws TypeError before any HTTP exchange. That's an environmental
+  // limit, not a code path; the bogus-reset-token test below covers the
+  // server-side error-mapping equivalent.
+});
+
+describe('[PWSX] Service.resetPassword', function () {
+  let service;
+
+  before(async function () {
+    this.timeout(15000);
+    await testData.prepare();
+    service = new pryv.Service(testData.serviceInfoUrl);
+  });
+
+  it('[PWSA] rejects when required args are missing', async function () {
+    let caught;
+    try {
+      await service.resetPassword(testData.username, 'newpw', '', 'jslib-test');
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).to.be.instanceOf(pryv.PryvError);
+  });
+
+  it('[PWSB] throws PryvError with structured fields on bogus reset token', async function () {
+    this.timeout(15000);
+    let caught;
+    try {
+      await service.resetPassword(
+        testData.username,
+        testData.password + 'X',
+        'bogus-reset-token-' + cuid().slice(0, 8),
+        'jslib-test'
+      );
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).to.be.instanceOf(pryv.PryvError);
+    expect(caught.status).to.be.gte(400);
+    expect(caught.response).to.have.property('status');
+  });
+});

package/test/Service.userExists.test.js

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, before, expect, pryv, testData */
+
+const { createId: cuid } = require('@paralleldrive/cuid2');
+
+describe('[USRX] Service.userExists', function () {
+  before(async function () {
+    this.timeout(15000);
+    await testData.prepare();
+  });
+
+  it('[USRA] returns true for a registered user', async function () {
+    this.timeout(15000);
+    const service = new pryv.Service(testData.serviceInfoUrl);
+    const exists = await service.userExists(testData.username);
+    expect(exists).to.equal(true);
+  });
+
+  it('[USRB] returns false for an unknown user (404)', async function () {
+    this.timeout(15000);
+    const service = new pryv.Service(testData.serviceInfoUrl);
+    const fakeUser = 'no-' + cuid().slice(0, 12);
+    const exists = await service.userExists(fakeUser);
+    expect(exists).to.equal(false);
+  });
+});

package/test/Service.userIdForEmail.test.js

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, before, expect, pryv, testData */
+
+const { createId: cuid } = require('@paralleldrive/cuid2');
+
+describe('[UEMX] Service.userIdForEmail', function () {
+  before(async function () {
+    this.timeout(15000);
+    await testData.prepare();
+  });
+
+  it('[UEMA] returns the username for a known email', async function () {
+    this.timeout(15000);
+    const service = new pryv.Service(testData.serviceInfoUrl);
+    const knownEmail = testData.username + '@pryv.io';
+    const userId = await service.userIdForEmail(knownEmail);
+    expect(userId).to.equal(testData.username);
+  });
+
+  it('[UEMB] returns null for an unknown email', async function () {
+    this.timeout(15000);
+    const service = new pryv.Service(testData.serviceInfoUrl);
+    const unknownEmail = 'ghost-' + cuid().slice(0, 12) + '@example.com';
+    const userId = await service.userIdForEmail(unknownEmail);
+    expect(userId).to.equal(null);
+  });
+});