import LoginResponseFields from "../../../src/reference/subbly-sdk/types/AuthResourceLoginResponse.mdx";

<SdkPage group="auth" />

A successful sign-in writes the access token to the `subbly_access_token`
cookie, sets the `Authorization` header on the shared HTTP client, and flips
`subbly.auth.isAuthenticated` to `true`. The cookie lasts 365 days and is set on
`path=/`. It is a plain cookie: the SDK sets no `Secure`, `HttpOnly` or
`SameSite` attribute, so treat it as readable by any script on the host.

<Method id="is-authenticated" signature="subbly.auth.isAuthenticated">

A `boolean` property, not a method. It is `true` after a successful
`checkAuthenticated`, `login`, `register`, `otpLogin` or `social`, and `false`
after `logout`. Nothing watches it, so read it after an authentication call
rather than expecting it to update on its own.

<Returns type="boolean">
`true` when the SDK holds a token it has checked.
</Returns>

<Example>

```js title="Branch on the authentication state"
if (subbly.auth.isAuthenticated) {
  const customer = await subbly.customers.me()
}
```

</Example>

</Method>

<Method id="check-authenticated" signature="subbly.auth.checkAuthenticated(token?)">

Verifies that the SDK can call the methods that need a signed-in customer.
`Subbly.init` calls it for you at start-up.

The check costs one request: it calls `subbly.customers.me()` behind the scenes.
When it passes, the SDK sets the `Authorization` header and, if you passed a
token, writes it to the cookie. When it fails, the SDK clears the header and the
cookie and logs the error to the console.

<Params>
  <Param name="token" optional type="string">
  An access token to check. It beats the token in the cookie. Leave it out to
  check the token already stored.
  </Param>
</Params>

<Returns type="Promise<boolean>">
`true` when the customer is signed in. It resolves with `false` rather than
rejecting when there is no token or the token is rejected.
</Returns>

<Example>

```js title="Check the stored token"
const signedIn = await subbly.auth.checkAuthenticated()
```

```js title="Check a token you hold"
const signedIn = await subbly.auth.checkAuthenticated('eyJh...eyJ9')
```

</Example>

</Method>

<Method id="login" signature="subbly.auth.login(payload)">

Signs the customer in with an email and a password.

<Params>
  <Param name="payload" required type="AuthResourceLoginPayload">
    The credentials.

    <Properties label="payload">
      <Param name="email" required type="string">
      Email address of the customer.
      </Param>
      <Param name="password" required type="string">
      Password of the customer.
      </Param>
    </Properties>
  </Param>
</Params>

<Returns type="Promise<AuthResourceLoginResponse>">
The new token. The SDK stores it for you.
<Properties label="response">
  <LoginResponseFields />
</Properties>
</Returns>

<Example>

```js title="Log in"
await subbly.auth.login({
  email: 'ada@example.com',
  password: 'correct horse battery staple',
})
```

</Example>

</Method>

<Method id="register" signature="subbly.auth.register(payload)">

Creates an account and signs the new customer in. It stores the token exactly as
`login` does.

<Params>
  <Param name="payload" required type="AuthResourceRegisterPayload">
    The new customer.

    <Properties label="payload">
      <Param name="email" required type="string">
      Email address. It must not already have a Subbly account.
      </Param>
      <Param name="firstName" required type="string">
      Given name.
      </Param>
      <Param name="lastName" required type="string">
      Family name.
      </Param>
      <Param name="password" optional type="string">
      Password. Leave it out and Subbly generates one and emails it to the
      customer.
      </Param>
    </Properties>
  </Param>
</Params>

<Returns type="Promise<AuthResourceLoginResponse>">
The new token, in the same shape `login` returns.
<Properties label="response">
  <LoginResponseFields />
</Properties>
</Returns>

<Example>

```js title="Register a customer"
await subbly.auth.register({
  email: 'ada@example.com',
  firstName: 'Ada',
  lastName: 'Lovelace',
})
```

</Example>

</Method>

<Method id="registered" signature="subbly.auth.registered(payload)">

Reports whether an email already has a Subbly account. Use it to send the
customer to the sign-in form instead of the sign-up form.

<Params>
  <Param name="payload" required type="AuthResourceRegisteredPayload">
    The email to look up.

    <Properties label="payload">
      <Param name="email" required type="string">
      Email address to check.
      </Param>
    </Properties>
  </Param>
</Params>

<Returns type="Promise<AuthResourceRegisteredResponse>">
The answer.
<Properties label="response">
  <Param name="registered" type="boolean">
  `true` when an account already exists for the email.
  </Param>
</Properties>
</Returns>

<Example>

```js title="Check an email"
const { registered } = await subbly.auth.registered({
  email: 'ada@example.com',
})
```

</Example>

</Method>

<Method id="otp" signature="subbly.auth.otp(payload)">

Emails a one-time password to the address you give. Pass the code the customer
types back to `subbly.auth.otpLogin`.

<Params>
  <Param name="payload" required type="AuthResourceOtpPayload">
    Where to send the code.

    <Properties label="payload">
      <Param name="email" required type="string">
      Email address to send the one-time password to.
      </Param>
    </Properties>
  </Param>
</Params>

<Returns type="Promise<void>">
Nothing. The response body is empty.
</Returns>

<Example>

```js title="Send a one-time password"
await subbly.auth.otp({ email: 'ada@example.com' })
```

</Example>

</Method>

<Method id="otp-login" signature="subbly.auth.otpLogin(payload)">

Signs the customer in with the one-time password `subbly.auth.otp` emailed. It
stores the token exactly as `login` does.

<Params>
  <Param name="payload" required type="AuthResourceOtpLoginPayload">
    The email and the code.

    <Properties label="payload">
      <Param name="email" required type="string">
      The address the code went to.
      </Param>
      <Param name="token" required type="string">
      The one-time password the customer typed, such as `123456`.
      </Param>
    </Properties>
  </Param>
</Params>

<Returns type="Promise<AuthResourceLoginResponse>">
The new token, in the same shape `login` returns.
<Properties label="response">
  <LoginResponseFields />
</Properties>
</Returns>

<Example>

```js title="Log in with a one-time password"
await subbly.auth.otpLogin({
  email: 'ada@example.com',
  token: '123456',
})
```

</Example>

</Method>

<Method id="social" signature="subbly.auth.social(payload)">

Signs the customer in with a Google or Facebook token. The provider must be
switched on for the shop; look for a `google_login` or `facebook_login` entry in
`subbly.shop.apps`. It stores the token exactly as `login` does.

<Params>
  <Param name="payload" required type="AuthResourceSocialPayload">
    The token from the provider.

    <Properties label="payload">
      <Param name="token" required type="string">
      The ID token the provider's own SDK gave you.
      </Param>
      <Param name="provider" required type="string">
      Which service issued the token: `google` or `facebook`.
      </Param>
    </Properties>
  </Param>
</Params>

<Returns type="Promise<AuthResourceLoginResponse>">
The new token, in the same shape `login` returns.
<Properties label="response">
  <LoginResponseFields />
</Properties>
</Returns>

<Example>

```js title="Log in with Google"
await subbly.auth.social({
  token: googleIdToken,
  provider: 'google',
})
```

</Example>

</Method>

<Method id="logout" signature="subbly.auth.logout()">

Clears the authentication state in the browser: it sets `isAuthenticated` to
`false`, drops the `Authorization` header, and empties the
`subbly_access_token` cookie.

It sends no request, so the token itself stays valid until it expires. Do not
rely on `logout` to lock anything down on the server.

<Returns type="void">
Nothing. This method is not a promise.
</Returns>

<Example>

```js title="Log out"
subbly.auth.logout()
```

</Example>

</Method>

<Method id="get-access-token" signature="subbly.auth.getAccessToken()">

Reads the access token out of the `subbly_access_token` cookie. It is
synchronous and makes no request. Use it to hand the token to your own backend.

<Returns type="string | null">
The stored token. `null` when there is no cookie, and an empty string after
`subbly.auth.logout()`. The TypeScript type says `string | undefined`; the SDK
never returns `undefined`.
</Returns>

<Example>

```js title="Read the access token"
const token = subbly.auth.getAccessToken()
```

</Example>

</Method>