fastify-xplaid

sandbox.resetItem(accessToken)

Force a sandbox Plaid Item into a login-required state for testing re-authentication flows.

sandbox.resetItem(accessToken)

Forces a sandbox Plaid Item into a login-required (ITEM_LOGIN_REQUIRED) error state. Plaid will fire an ITEM / ERROR webhook with error_code: ITEM_LOGIN_REQUIRED. Use this to test your re-authentication flow — typically triggered by calling link.createToken with the Item's access token in update mode.

This method will throw if called outside of the sandbox environment. Do not include sandbox helper calls in production code paths.

Signature

fastify.xplaid.sandbox.resetItem(
  accessToken: string
): Promise<{ resetLogin: boolean; requestId: string }>

Params

Name	Type	Required	Description
`accessToken`	`string`	Yes	The access token for the sandbox Item to reset.

Returns

Promise<{ resetLogin: boolean, requestId: string }>

Field	Type	Description
`resetLogin`	`boolean`	`true` if the reset was successful.
`requestId`	`string`	Plaid request ID for logging.

Throws

[xPlaid] accessToken is required and must be a non-empty string
Plaid API errors — shape: { message, statusCode, plaidError }.
Will throw if called in development or production environments.

Examples

Basic — reset an Item

const { resetLogin } = await fastify.xplaid.sandbox.resetItem(accessToken);
console.log(resetLogin); // true
// Now any data call with this accessToken will throw ITEM_LOGIN_REQUIRED

Realistic — test re-authentication flow end-to-end

test("reauth flow: reset item, create update-mode link token, re-exchange", async (t) => {
  // 1. Create a fresh sandbox item
  const { publicToken } = await fastify.xplaid.sandbox.createPublicToken(
    "ins_109508",
    ["transactions"]
  );
  const { accessToken } = await fastify.xplaid.link.exchangePublicToken(publicToken);

  // 2. Reset to ITEM_LOGIN_REQUIRED state
  const { resetLogin } = await fastify.xplaid.sandbox.resetItem(accessToken);
  t.ok(resetLogin, "item should be reset");

  // 3. Data calls now fail with ITEM_ERROR
  try {
    await fastify.xplaid.transactions.sync(accessToken);
    t.fail("Should have thrown ITEM_LOGIN_REQUIRED");
  } catch (error) {
    t.equal(error.plaidError?.error_code, "ITEM_LOGIN_REQUIRED");
  }

  // 4. Create update-mode link token to simulate re-auth
  const { linkToken } = await fastify.xplaid.link.createToken({
    userId: "test_user",
    accessToken, // triggers update mode
  });
  t.ok(linkToken, "should get a link token for update mode");
});

AI Context

package: "@xenterprises/fastify-xplaid"
method: fastify.xplaid.sandbox.resetItem(accessToken)
use-when: Sandbox testing — force an Item into ITEM_LOGIN_REQUIRED state to test re-authentication flows
environment: sandbox only
returns: { resetLogin, requestId }

Edit this pageorReport an issue

sandbox.createPublicToken(institutionId, initialProducts)

Create a Plaid public token in the sandbox environment without the Link UI.

transactions.get(accessToken, startDate, endDate, options?)

Fetch transactions by date range for a Plaid Item.