@autofleet/element-pay

GraphQL client for the Element Pay third-party provider. Exposes two authenticated SDK factories (organization-scoped and user-scoped) and a PubSub message transformer for service-location events.

Environments

| Key | Endpoint | |---------|--------------------------------------------| | int | https://api-gateway.int.gocariq.com/ | | stage | https://api-gateway.stage.gocariq.com/ |

Default environment: stage.

API

getOrganizationSdk(config)

Returns a GraphQL SDK authenticated with an API key (organization-level operations).

import { getOrganizationSdk } from '@autofleet/element-pay';

const sdk = getOrganizationSdk({
  apiKey: 'your-api-key',
  environment: 'int', // optional, defaults to 'stage'
  // endpoint: 'https://custom-endpoint/' // optional override
});

Config:

| Field | Type | Required | Description | |---------------|------------------------|----------|------------------------------------| | apiKey | string | Yes | Sent as x-api-key header | | environment | 'int' \| 'stage' | No | Defaults to 'stage' | | endpoint | string | No | Overrides environment endpoint |

Available mutations/queries (from src/graphql/organization/):

• createOrganization
• entityCreate
• entityGetExternalId
• apiKeyCreate
• clientOnboarding
• machineTokenizeUser
• userCreate
• userUpdate
• userOffboard
• vehicleGroupCreate
• vehicleGroupDriversAdd
• vehicleGroupDriversRemove
• vehicleGroupVehiclesAdd
• vehicleGroupVehiclesRemove
• vehicleGroupDelete
• vehiclesOnboard
• vehiclesFilter
• vehiclesGroupFilter
• vehicleUpdate
• standaloneCardCreate

getUserSdk(config)

Returns a GraphQL SDK authenticated with a user access token (user-level operations).

import { getUserSdk } from '@autofleet/element-pay';

const sdk = getUserSdk({
  accessToken: 'bearer-token',
  environment: 'int', // optional, defaults to 'stage'
  // endpoint: 'https://custom-endpoint/' // optional override
});

Config:

| Field | Type | Required | Description | |---------------|------------------------|----------|------------------------------------| | accessToken | string | Yes | Sent as Authorization: Bearer | | environment | 'int' \| 'stage' | No | Defaults to 'stage' | | endpoint | string | No | Overrides environment endpoint |

Available mutations/queries (from src/graphql/user/):

• servicePay
• provisionCard
• provisionStatusUpdate
• ttpTokenization

serviceLocationPubSubMessageToFuelSupplier(message)

Decodes a msgpack-encoded PubSub message containing a ServiceLocationEvent and transforms it into a partial FuelSupplier object.

import { serviceLocationPubSubMessageToFuelSupplier } from '@autofleet/element-pay';

const fuelSupplier = serviceLocationPubSubMessageToFuelSupplier(rawPubSubMessage);
// Returns: Partial<FuelSupplier>

Mapped fields:

| Output field | Source | |---------------------|---------------------------------------------| | acceptElementPay | Always true | | address | Joined from address fields | | externalId | ServiceLocation.id | | name | ServiceLocation.name | | brandName | Mapped from provider.name via consts | | lat / lng | ServiceLocation.geocoded | | directPayEnabled | !out_of_network | | ttpEnabled | ServiceLocation.ttp_enabled | | isActive | enabled && !deleted_at |

Codegen

npm codegen:user         # regenerates src/generated/user/sdk.ts
npm codegen:organization # regenerates src/generated/organization/sdk.ts

Adding new capabilities

1. Add a GraphQL file

Create a .graphql file in the appropriate directory:

• Organization operations → src/graphql/organization/
• User operations → src/graphql/user/

Name the file after the operation (e.g. vehicle-group-delete.graphql). Follow the existing patterns — mutations that return an object should select the fields you need; mutations that return a scalar need no selection set.

# Example: src/graphql/organization/vehicle-group-delete.graphql
mutation vehicleGroupDelete($id: ID!) {
  vehicleGroupDelete(id: $id)
}

2. Run codegen

Regenerate the typed SDK for the affected scope:

npm run codegen:organization   # if you added to src/graphql/organization/
npm run codegen:user           # if you added to src/graphql/user/

This updates src/generated/{organization,user}/sdk.ts and makes the new operation available on the SDK object.

3. Add to src/index.test.ts (organization operations)

For organization-level operations, add a helper function and call it in the 'full onboarding and pay flow' test. Follow the existing pattern:

const vehicleGroupDelete = async (vehicleGroupId: string) => {
  const result = await organizationSdkForOrganization.vehicleGroupDelete({ id: vehicleGroupId });
  expect(result.vehicleGroupDelete).toEqual('SUCCESS');
  return result.vehicleGroupDelete;
};

Then call it at the appropriate point in the test flow (respect logical ordering — e.g. cleanup operations go after the main flow). User-level operations follow the same pattern using getUserSdk.