feathersjs-ecosystem/feathers-authentication-management

View on GitHub
docs/service-calls.md

Summary

Maintainability
Test Coverage
# Service Calls

The `feathers-authentication-management` service methods can be called using various ways. These can be external calls from the client as well as internal calls within the server. On client side, you can use the [Feathers client](https://docs.feathersjs.com/api/client.html), plain and simple HTTP requests, or any other request library your frontend framework provides.

The service may be called using

- Direct Feathers service calls,
- HTTP requests on the Feathers API,
- Provided service wrappers (see last section).

## Comparison of the different service calls

There are three ways of calling a method:
1. Main service as `AuthenticationManagementService` with `create` and `action`
2. Separate services (e.g. `SendResetPwdService`) with `create`
3. Main service as `AuthenticationManagementService` with custom method (e.g. `sendResetPassword`)

<Tabs show-tabs>

  <Tab name="Main Service" active>

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service("auth-management").create({
  action: "sendResetPwd",
  value: {
    email: "me@example.com",
  },
});
```

  </Tab>

  <Tab name="Separate Service">

```js
// const { SendResetPwdService } = require('feathers-authentication-management');
// app.use("auth-management/send-reset-password", new SendResetPwdService(app, options));

app.service("auth-management/send-reset-password").create({
  user: {
    email: "me@example.com",
  },
});
```

  </Tab>

  <Tab name="Custom Method">

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service("auth-management").sendResetPassword({
  user: {
    email: "me@example.com",
  },
});
```

  </Tab>
  
</Tabs>

## checkUnique

Checks if the properties are unique in the users items.

<Tabs show-tabs>

  <Tab name="Main Service" active>

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').create({
  action: 'checkUnique',
  value: identifyUser, // e. g. {email: 'a@a.com'} or  {username: 'jane'}. Props with null or undefined are ignored.
  ownId, // Excludes user with ownId from the search
  meta: { noErrMsg } // if return an error.message if not unique
}
```

  </Tab>

  <Tab name="Separate Service">

```js
// const { CheckUniqueService } = require('feathers-authentication-management');
// app.use("auth-management/check-unique", new CheckUniqueService(app, options));

app.service('auth-management/check-unique').create({
  user: identifyUser, // e. g. {email: 'a@a.com'} or  {username: 'jane'}. Props with null or undefined are ignored.
  ownId, // Excludes user with ownId from the search
  meta: { noErrMsg } // if return an error.message if not unique
}
```

  </Tab>

  <Tab name="Custom Method">

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').checkUnique({
  user: identifyUser, // e. g. {email: 'a@a.com'} or  {username: 'jane'}. Props with null or undefined are ignored.
  ownId, // Excludes user with ownId from the search
  meta: { noErrMsg } // if return an error.message if not unique
}
```

  </Tab>
  
</Tabs>

Returns `null` if the properties are unique (= already existing) in the users items. Otherwise rejects with `BadRequest`.

## identityChange

Changes the communication address of a user, e. g. the e-mail address or a phone number.

<Tabs show-tabs>

  <Tab name="Main Service" active>

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').create({
  action: 'identityChange',
  value: {
    user: identifyUser, // identify user, e.g. {email: 'a@a.com'}. See options.identifyUserProps.
    password, // current password for verification
    changes, // {email: 'a@a.com'} or {email: 'a@a.com', cellphone: '+1-800-555-1212'}
  },
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Separate Service">

```js
// const { IdentityChangeService } = require('feathers-authentication-management');
// app.use("auth-management/identity-change", new IdentityChangeService(app, options));

app.service('auth-management/identity-change').create({
  user: identifyUser, // identify user, e.g. {email: 'a@a.com'}. See options.identifyUserProps.
  password, // current password for verification
  changes, // {email: 'a@a.com'} or {email: 'a@a.com', cellphone: '+1-800-555-1212'}
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Custom Method">

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').identityChange({
  user: identifyUser, // identify user, e.g. {email: 'a@a.com'}. See options.identifyUserProps.
  password, // current password for verification
  changes, // {email: 'a@a.com'} or {email: 'a@a.com', cellphone: '+1-800-555-1212'}
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>
  
</Tabs>

Returns the user object or rejects with `BadRequest`.

## passwordChange

Changes the password of a user.

<Tabs show-tabs>

  <Tab name="Main Service" active>

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').create({
  action: 'passwordChange',
  value: {
    user: identifyUser, // identify user, e.g. {email: 'a@a.com'}. See options.identifyUserProps.
    oldPassword, // old password for verification
    password, // new password
  },
  notifierOptions: {} // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Separate Service">

```js
// const { PasswordChangeService } = require('feathers-authentication-management');
// app.use("auth-management/password-change", new PasswordChangeService(app, options));

app.service('auth-management/password-change').create({
  user: identifyUser, // identify user, e.g. {email: 'a@a.com'}. See options.identifyUserProps.
  oldPassword, // old password for verification
  password, // new password
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Custom Method">

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').passwordChange({
  user: identifyUser, // identify user, e.g. {email: 'a@a.com'}. See options.identifyUserProps.
  oldPassword, // old password for verification
  password, // new password
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>
  
</Tabs>

Returns the user object or rejects with `BadRequest`.

## resendVerifySignup

Recreates a long and/or short verification token, stores it to the user item, and triggers the notifier function to send the token to the user.

<Tabs show-tabs>

  <Tab name="Main Service" active>

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').create({
  action: 'resendVerifySignup',
  value: identifyUser, // {email}, {token: verifyToken}
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Separate Service">

```js
// const { ResendVerifySignupService } = require('feathers-authentication-management');
// app.use('auth-management/resend-verify-signup', new ResendVerifySignupService(app, options));

app.service('auth-management/resend-verify-signup').create({
  user: identifyUser, // {email}, {token: verifyToken}
  notifierOptions: {}, // options passed to options.notifier
}
```

  </Tab>

  <Tab name="Custom Method">

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').resendVerifySignup({
  user: identifyUser, // {email}, {token: verifyToken}
  notifierOptions: {}, // options passed to options.notifier
}
```

  </Tab>
  
</Tabs>

Returns the user object or rejects with `BadRequest`.

## resetPwdLong

Stores a new password. Requires a valid long `resetToken`.

<Tabs show-tabs>

  <Tab name="Main Service" active>

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').create({
  action: 'resetPwdLong',
  value: {
    token, // compares to resetToken
    password, // new password
  },
  notifierOptions: {}, // optional - an object passed to notifier function
}


```

  </Tab>

  <Tab name="Separate Service">

```js
// const { ResetPwdLongService } = require('feathers-authentication-management');
// app.use('auth-management/reset-pwd-long', new ResetPwdLongService(app, options));

app.service('auth-management/reset-pwd-long').create({
  token, // compares to resetToken
  password, // new password
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Custom Method">

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').resetPasswordLong({
  token, // compares to resetToken
  password, // new password
  notifierOptions: {}, // optional - an object passed to notifier function
}

```

  </Tab>
  
</Tabs>

Returns the user object or rejects with `BadRequest`.

## resetPwdShort

Stores a new password. Requires a valid short `resetShortToken` and a property of the user object to identify the user.

<Tabs show-tabs>

  <Tab name="Main Service" active>

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').create({
  action: 'resetPwdShort',
  value: {
    user: identifyUser, // identify user, e.g. {email: 'a@a.com'}. See options.identifyUserProps.
    token, // compares to .resetShortToken
    password, // new password
  },
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Separate Service">

```js
// const { ResetPwdShortService } = require('feathers-authentication-management');
// app.use('auth-management/reset-password-short', new ResetPwdShortService(app, options));

app.service('auth-management/reset-password-short').create({
  user: identifyUser, // identify user, e.g. {email: 'a@a.com'}. See options.identifyUserProps.
  token, // compares to .resetShortToken
  password, // new password
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Custom Method">

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').resetPasswordShort({
  user: identifyUser, // identify user, e.g. {email: 'a@a.com'}. See options.identifyUserProps.
  token, // compares to .resetShortToken
  password, // new password
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>
  
</Tabs>

Returns the user object or rejects with `BadRequest`.

## sendResetPwd

Creates a short and/or long password reset token, stores it to the user item, and triggers the notifier function to send the token to the user.

<Tabs show-tabs>

  <Tab name="Main Service" active>

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').create({
  action: 'sendResetPwd',
  value: identifyUser, // {email}, {token: verifyToken}
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Separate Service">

```js
// const { SendResetPwdService } = require('feathers-authentication-management');
// app.use("auth-management/send-reset-password", new SendResetPwdService(app, options));

app.service('auth-management/send-reset-password').create({
  user: identifyUser, // {email}, {token: verifyToken}
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Custom Method">

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').sendResetPassword({
  user: identifyUser, // {email}, {token: verifyToken}
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>
  
</Tabs>

Returns the user object or rejects with `BadRequest`.

## verifySignupLong

Verifies a given long verification token.

<Tabs show-tabs>

  <Tab name="Main Service" active>

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').create({
  action: 'verifySignupLong',
  value: verifyToken, // compares to .verifyToken
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Separate Service">

```js
// const { VerifySignupLongService } = require('feathers-authentication-management');
// app.use("auth-management/verify-signup-long", new VerifySignupLongService(app, options));

app.service('auth-management/verify-signup-long').create({
  token: verifyToken, // compares to .verifyToken
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Custom Method">

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').verifySignupLong({
  token: verifyToken, // compares to .verifyToken
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>
  
</Tabs>

Returns the user object or rejects with `BadRequest`.

## verifySignupShort

Verifies a given short verification token.

<Tabs show-tabs>

  <Tab name="Main Service" active>

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').create({
  action: 'verifySignupShort',
  value: {
    user, // identify user, e.g. {email: 'a@a.com'}. See options.identifyUserProps.
    token, // compares to .verifyShortToken
  },
  notifierOptions: {}, // optional - an object passed to notifier function
}

```

  </Tab>

  <Tab name="Separate Service">

```js
// const { VerifySignupShortService } = require('feathers-authentication-management');
// app.use("auth-management/verify-signup-short", new VerifySignupShortService(app, options));

app.service('auth-management/verify-signup-short').create({
  user, // identify user, e.g. {email: 'a@a.com'}. See options.identifyUserProps.
  token, // compares to .verifyShortToken
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Custom Method">

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').verifySignupShort({
  user, // identify user, e.g. {email: 'a@a.com'}. See options.identifyUserProps.
  token, // compares to .verifyShortToken
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>
  
</Tabs>

Returns the user object or rejects with `BadRequest`.

## verifySignupSetPasswordLong

This is a combination of `verifySignupLong` and `resetPwdLong`: Verifies a given long verification token and stores the new password.

<Tabs show-tabs>

  <Tab name="Main Service" active>

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').create({
  action: 'verifySignupSetPasswordLong',
  value: {
    token, // compares to .verifyToken
    password, // new password
  },
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Separate Service">

```js
// const { VerifySignupSetPasswordLongService } = require('feathers-authentication-management');
// app.use("auth-management/verify-signup-set-password-long", new VerifySignupSetPasswordLongService(app, options));

app.service('auth-management/verify-signup-set-password-long').create({
  token, // compares to .verifyToken
  password, // new password
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Custom Method">

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').verifySignupSetPasswordLong({
  token, // compares to .verifyToken
  password, // new password
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>
  
</Tabs>

Returns the user object or rejects with `BadRequest`.

## verifySignupSetPasswordShort

This is a combination of `verifySignupShort` and `resetPwdShort`: Verifies a given short verification token and stores the new password.

<Tabs show-tabs>

  <Tab name="Main Service" active>

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').create({
  action: 'verifySignupSetPasswordShort',
  value: {
    user, // identify user, e.g. {email: 'a@a.com'}. See options.identifyUserProps.
    token, // compares to .verifyShortToken
    password, // new password
  },
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Separate Service">

```js
// const { VerifySignupSetPasswordShortService } = require('feathers-authentication-management');
// app.use("auth-management/verify-signup-set-password-short", new VerifySignupSetPasswordShortService(app, options));

app.service('auth-management/verify-signup-set-password-short').create({
  user, // identify user, e.g. {email: 'a@a.com'}. See options.identifyUserProps.
  token, // compares to .verifyShortToken
  password, // new password
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>

  <Tab name="Custom Method">

```js
// const { AuthenticationManagementService } = require('feathers-authentication-management');
// app.use('auth-management', new AuthenticationManagementService(app, options));

app.service('auth-management').verifySignupSetPasswordShort({
  user, // identify user, e.g. {email: 'a@a.com'}. See options.identifyUserProps.
  token, // compares to .verifyShortToken
  password, // new password
  notifierOptions: {}, // optional - an object passed to notifier function
}
```

  </Tab>
  
</Tabs>

Returns the user object or rejects with `BadRequest`.