@dimo-network/data-sdk 1.2.2 → 1.2.4

package/.github/workflows/npm-publish.yml

@@ -15,8 +15,12 @@ jobs:
       - uses: actions/setup-node@v3
         with:
           node-version: 20
-      - run: npm ci
-      - run: npm test
+      - name: Clear npm cache
+        run: npm cache clean --force
+      - name: Install dependencies
+        run: npm ci
+      - name: Run tests
+        run: npm test
       - name: Run build
         run: npm run build
       - name: Check dist directory
@@ -31,8 +35,12 @@ jobs:
         with:
           node-version: 20
           registry-url: https://registry.npmjs.org/
-      - run: npm ci
-      - run: npm test
+      - name: Clear npm cache
+        run: npm cache clean --force
+      - name: Install dependencies
+        run: npm ci
+      - name: Run tests
+        run: npm test
       - name: Run build
         run: npm run build
       - name: Check dist directory

package/README.md

@@ -29,10 +29,17 @@ Please visit the DIMO [Developer Documentation](https://docs.dimo.org/developer-
 ## How to Use the SDK
 
 Import the SDK library:
+
+(TypeScript / ES Modules)
 ```ts
 import { DIMO } from '@dimo-network/data-sdk';
 ```
 
+(CommonJS)
+```js
+const { DIMO } = require('@dimo-network/data-sdk')
+```
+
 Initiate the SDK:
 
 ```ts
@@ -48,33 +55,28 @@ As part of the authentication process, you will need to obtain a Developer Licen
 
 ### Authentication
 
-The SDK provides you with all the steps needed in the [Authentication Flow](https://docs.dimo.org/developer-platform/getting-started/developer-guide/authentication) to obtain a Developer JWT.
+The SDK provides you with all the steps needed in the [Authentication Flow](https://docs.dimo.org/developer-platform/getting-started/developer-guide/authentication) to obtain a Developer JWT & to get Vehicle JWT for each vehicle shared with your app.
 
-#### Prerequisites for Authentication
-1. A valid Developer License with a `client_id`
-2. A valid API key, generated via the Developer Console
 3. A proper [project set up with TypeScript](https://www.digitalocean.com/community/tutorials/setting-up-a-node-project-with-typescript).
 
-#### API Authentication
+#### Developer JWT
+To get a Developer JWT, you will need a valid Developer License with a `client_id`, a generated `api_key`, and a `domain`/`redirect_uri` you configured on the Developer Console.
 
-##### (Option 1 - PREFERRED) getToken Function
+##### (Option 1 - PREFERRED) getDeveloperJwt Function
 This is a utility function call to get a Developer JWT in one step:
 
 ```ts
-const developerJwt = await dimo.auth.getToken({
+const developerJwt = await dimo.auth.getDeveloperJwt({
   client_id: '<client_id>',
-  domain: '<domain>',
+  domain: '<domain/redirect_uri>',
   private_key: '<api_key>',
 });
 ```
 
-Once you have the `developerJwt`, you'll have access to the DIMO API endpoints. For endpoints that require the authorization headers, you can simply pass the results.
+Once you have the `developerJwt`, you'll have access to the DIMO API as a verified developer. For endpoints that require the authorization headers, you can simply pass the results.
 
 ```ts
 // Pass the developerJwt object to a protected endpoint
-await dimo.user.get(developerJwt);
-
-// Pass the developerJwt object to a protected endpoint with body parameters
 await dimo.tokenexchange.exchange({
   ...developerJwt,
   privileges: [4],
@@ -94,6 +96,54 @@ const developerJwt = await dimo.authenticate();
 // The rest would be the same as option 1
 ```
 
+#### Vehicle JWT
+
+To get vehicle data from an end user, your application will need to exchange for a short-lived [Vehicle JWT](https://docs.dimo.org/developer-platform/getting-started/developer-guide/authentication#getting-a-jwt) for vehicles that have granted permissions to your app. 
+
+For the end users of your application, they will need to have already shared their vehicle permissions via the DIMO Mobile App or via your implementation of [Login with DIMO](https://docs.dimo.org/developer-platform/getting-started/developer-guide/login-with-dimo) before you can fetch for their vehicle data.
+
+##### (Option 1 - PREFERRED) getVehicleJwt Function
+This is a utility function call to get a Vehicle JWT in one step by inputting your developer JWT obtained earlier with the vehicle's identifier (`tokenId`):
+
+```ts
+const vehicleJwt = await dimo.tokenexchange.getVehicleJwt({
+  ...developerJwt,
+  tokenId: 117315
+});
+```
+
+##### (Option 2) Manually exchanging for Vehicle JWT
+
+```ts
+const vehicle_jwt = await dimo.tokenexchange.exchange({
+  ...auth,
+  privileges: [1, 5],
+  tokenId: <vehicle_token_id>
+});
+```
+
+Once you have the `vehicleJwt`, you'll have access to the vehicle data for a specific vehicle. For endpoints that require the authorization headers, you can pass the results.
+
+```ts
+// Vehicle Status uses privId 1
+await dimo.devicedata.getVehicleStatus({
+  ...vehicle_jwt,
+  tokenId: <vehicle_token_id>
+});
+
+// Proof of Movement Verifiable Credentials uses privId 4
+await dimo.attestation.createPomVC({
+  ...vehicle_jwt,
+  tokenId: <vehicle_token_id>
+})
+
+// VIN Verifiable Credentials uses privId 5
+await dimo.attestation.createVinVC({
+  ...vehicle_jwt,
+  tokenId: <vehicle_token_id>
+});
+```
+
 ### Querying the DIMO REST API
 The SDK supports async await and your typical JS Promises. HTTP operations can be utilized in either ways:
 
@@ -139,41 +189,9 @@ dimo.attestation.createVinVC({
 })
 ```
 
-#### Vehicle JWT
-
-As the 2nd leg of the API authentication, applications may exchange for short-lived [Vehicle JWT](https://docs.dimo.org/developer-platform/getting-started/developer-guide/authentication#getting-a-jwt) for specific vehicles that granted permissions to the app. This uses the [DIMO Token Exchange API](https://docs.dimo.org/developer-platform/api-references/dimo-protocol/token-exchange-api/token-exchange-api-endpoints). 
-
-For the end users of your application, they will need to share their vehicle permissions via the DIMO Mobile App or via your implementation of [Login with DIMO](https://docs.dimo.org/developer-platform/getting-started/developer-guide/login-with-dimo) or even by sharing on the Vehicle NFT directly. Once vehicles are shared, you will be able to get a Vehicle JWT.
-
-```ts
-const vehicle_jwt = await dimo.tokenexchange.exchange({
-  ...auth,
-  privileges: [1, 5],
-  tokenId: <vehicle_token_id>
-});
-
-// Vehicle Status uses privId 1
-await dimo.devicedata.getVehicleStatus({
-  ...vehicle_jwt,
-  tokenId: <vehicle_token_id>
-});
-
-// Proof of Movement Verifiable Credentials uses privId 4
-await dimo.attestation.createPomVC({
-  ...vehicle_jwt,
-  tokenId: <vehicle_token_id>
-})
-
-// VIN Verifiable Credentials uses privId 5
-await dimo.attestation.createVinVC({
-  ...vehicle_jwt,
-  tokenId: <vehicle_token_id>
-});
-```
-
 ### Querying the DIMO GraphQL API
 
-The SDK accepts any type of valid custom GraphQL queries, but we've also included a few sample queries to help you understand the DIMO GraphQL APIs. 
+The SDK accepts any type of valid custom GraphQL queries, but we've also included a few sample queries to help you understand the DIMO GraphQL APIs. There's also a helper function called `paginate` that you can use to paginate through the GraphQL pages, see `getVehiclePrivileges.ts` on how it's being used.
 
 #### Authentication for GraphQL API
 The GraphQL entry points are designed almost identical to the REST API entry points. For any GraphQL API that requires auth headers (Telemetry API for example), you can use the same pattern as you would in the REST protected endpoints.

package/dist/api/Method.d.ts

@@ -1,2 +1,2 @@
 import { DimoEnvironment } from '../environments';
-export declare const Method: (resource: any, baseUrl: any, params: any, env: keyof typeof DimoEnvironment) => Promise<any>;
+export declare const Method: (resource: any, baseUrl: any, params: any | undefined, env: keyof typeof DimoEnvironment) => Promise<any>;

package/dist/api/functions/{getToken.d.ts → getDeveloperJwt.d.ts}

@@ -1,5 +1,5 @@
 import { DimoEnvironment } from '../../environments';
-export declare const getToken: (input: {
+export declare const getDeveloperJwt: (input: {
     client_id: string;
     domain: string;
     private_key: string;

package/dist/api/functions/{getToken.js → getDeveloperJwt.js}

@@ -1,5 +1,5 @@
 import { DIMO } from '../../dimo';
-export const getToken = async (input, env) => {
+export const getDeveloperJwt = async (input, env) => {
     const sdk = new DIMO(env);
     const challenge = await sdk.auth.generateChallenge({
         client_id: input.client_id,

package/dist/api/functions/getVehicleJwt.d.ts

@@ -0,0 +1,7 @@
+import { DimoEnvironment } from '../../environments';
+export declare const getVehicleJwt: (input: {
+    headers: {
+        Authorization: string;
+    };
+    tokenId: number;
+}, env: keyof typeof DimoEnvironment) => Promise<any>;

package/dist/api/functions/getVehicleJwt.js

@@ -0,0 +1,23 @@
+import { DIMO } from '../../dimo';
+import { decodeJwt, decodePermissions } from '../../util';
+export const getVehicleJwt = async (input, env) => {
+    const sdk = new DIMO(env);
+    const developerJwt = input.headers.Authorization;
+    if (!developerJwt || !developerJwt.startsWith('Bearer ')) {
+        throw new Error('Invalid Authorization header format');
+    }
+    // Remove "Bearer " prefix
+    const decodedToken = decodeJwt(developerJwt.slice(7));
+    const clientId = decodedToken.ethereum_address;
+    const privileges = await sdk.identity.getVehiclePrivileges({
+        tokenId: input.tokenId,
+        clientId: clientId // We want to pass in the clientId
+    });
+    const decodedPrivileges = decodePermissions(privileges[0].permissions);
+    const vehicleJwt = await sdk.tokenexchange.exchange({
+        ...input,
+        privileges: decodedPrivileges,
+        tokenId: input.tokenId
+    });
+    return vehicleJwt;
+};

package/dist/api/functions/index.d.ts

@@ -1,3 +1,4 @@
-import { getToken } from "./getToken";
+import { getDeveloperJwt } from "./getDeveloperJwt";
+import { getVehicleJwt } from "./getVehicleJwt";
 import { signChallenge } from "./signChallenge";
-export { getToken, signChallenge };
+export { getDeveloperJwt, getVehicleJwt, signChallenge };

package/dist/api/functions/index.js

@@ -1,3 +1,4 @@
-import { getToken } from "./getToken";
+import { getDeveloperJwt } from "./getDeveloperJwt";
+import { getVehicleJwt } from "./getVehicleJwt";
 import { signChallenge } from "./signChallenge";
-export { getToken, signChallenge };
+export { getDeveloperJwt, getVehicleJwt, signChallenge };

package/dist/api/resources/Auth/index.js

@@ -33,9 +33,9 @@ export class Auth extends Resource {
                 },
                 return: 'developer_jwt'
             },
-            getToken: {
+            getDeveloperJwt: {
                 method: 'FUNCTION',
-                path: 'getToken'
+                path: 'getDeveloperJwt'
             }
         });
     }

package/dist/api/resources/TokenExchange/index.js

@@ -14,6 +14,10 @@ export class TokenExchange extends Resource {
                 },
                 auth: 'developer_jwt',
                 return: 'vehicle_jwt'
+            },
+            getVehicleJwt: {
+                method: 'FUNCTION',
+                path: 'getVehicleJwt'
             }
         });
     }

package/dist/constants.d.ts

@@ -7,5 +7,8 @@ export declare const DimoConstants: {
         readonly NFT_address: "0x45fbCD3ef7361d156e8b16F5538AE36DEdf61Da8";
         readonly RPC_provider: "https://eth.llamarpc.com";
     };
+    readonly Query: {
+        readonly PAGE_SIZE: 100;
+    };
 };
-export type DimoConstants = typeof DimoConstants.Production | typeof DimoConstants.Dev;
+export type DimoConstants = typeof DimoConstants.Production | typeof DimoConstants.Dev | typeof DimoConstants.Query;

package/dist/constants.js

@@ -6,5 +6,8 @@ export const DimoConstants = {
     Dev: {
         'NFT_address': '0x45fbCD3ef7361d156e8b16F5538AE36DEdf61Da8',
         'RPC_provider': 'https://eth.llamarpc.com',
+    },
+    Query: {
+        'PAGE_SIZE': 100
     }
 };

package/dist/dimo.js

@@ -47,7 +47,7 @@ export class DIMO {
             }
             const data = fs.readFileSync('.credentials.json', 'utf8');
             const credentials = JSON.parse(data);
-            const authHeader = await this.auth.getToken({
+            const authHeader = await this.auth.getDeveloperJwt({
                 client_id: credentials.client_id,
                 domain: credentials.redirect_uri,
                 private_key: credentials.private_key,

package/dist/environments/index.d.ts

@@ -4,13 +4,10 @@ export declare const DimoEnvironment: {
         readonly Auth: "https://auth.dimo.zone";
         readonly Identity: "https://identity-api.dimo.zone/query";
         readonly Devices: "https://devices-api.dimo.zone";
-        readonly DeviceData: "https://device-data-api.dimo.zone";
         readonly DeviceDefinitions: "https://device-definitions-api.dimo.zone";
-        readonly Events: "https://events-api.dimo.zone";
         readonly Telemetry: "https://telemetry-api.dimo.zone/query";
         readonly TokenExchange: "https://token-exchange-api.dimo.zone";
         readonly Trips: "https://trips-api.dimo.zone";
-        readonly User: "https://users-api.dimo.zone";
         readonly Valuations: "https://valuations-api.dimo.zone";
         readonly VehicleSignalDecoding: "https://vehicle-signal-decoding.dimo.zone";
     };
@@ -19,13 +16,10 @@ export declare const DimoEnvironment: {
         readonly Auth: "https://auth.dev.dimo.zone";
         readonly Identity: "https://identity-api.dev.dimo.zone/query";
         readonly Devices: "https://devices-api.dev.dimo.zone";
-        readonly DeviceData: "https://device-data-api.dev.dimo.zone";
         readonly DeviceDefinitions: "https://device-definitions-api.dev.dimo.zone";
-        readonly Events: "https://events-api.dev.dimo.zone";
         readonly Telemetry: "https://telemetry-api.dev.dimo.zone/query";
         readonly TokenExchange: "https://token-exchange-api.dev.dimo.zone";
         readonly Trips: "https://trips-api.dev.dimo.zone";
-        readonly User: "https://users-api.dev.dimo.zone";
         readonly Valuations: "https://valuations-api.dev.dimo.zone";
         readonly VehicleSignalDecoding: "https://vehicle-signal-decoding.dev.dimo.zone";
     };

package/dist/environments/index.js

@@ -4,13 +4,10 @@ export const DimoEnvironment = {
         'Auth': 'https://auth.dimo.zone',
         'Identity': 'https://identity-api.dimo.zone/query',
         'Devices': 'https://devices-api.dimo.zone',
-        'DeviceData': 'https://device-data-api.dimo.zone',
         'DeviceDefinitions': 'https://device-definitions-api.dimo.zone',
-        'Events': 'https://events-api.dimo.zone',
         'Telemetry': 'https://telemetry-api.dimo.zone/query',
         'TokenExchange': 'https://token-exchange-api.dimo.zone',
         'Trips': 'https://trips-api.dimo.zone',
-        'User': 'https://users-api.dimo.zone',
         'Valuations': 'https://valuations-api.dimo.zone',
         'VehicleSignalDecoding': 'https://vehicle-signal-decoding.dimo.zone'
     },
@@ -19,13 +16,10 @@ export const DimoEnvironment = {
         'Auth': 'https://auth.dev.dimo.zone',
         'Identity': 'https://identity-api.dev.dimo.zone/query',
         'Devices': 'https://devices-api.dev.dimo.zone',
-        'DeviceData': 'https://device-data-api.dev.dimo.zone',
         'DeviceDefinitions': 'https://device-definitions-api.dev.dimo.zone',
-        'Events': 'https://events-api.dev.dimo.zone',
         'Telemetry': 'https://telemetry-api.dev.dimo.zone/query',
         'TokenExchange': 'https://token-exchange-api.dev.dimo.zone',
         'Trips': 'https://trips-api.dev.dimo.zone',
-        'User': 'https://users-api.dev.dimo.zone',
         'Valuations': 'https://valuations-api.dev.dimo.zone',
         'VehicleSignalDecoding': 'https://vehicle-signal-decoding.dev.dimo.zone'
     }

package/dist/graphql/Query.d.ts

@@ -1,3 +1,3 @@
 import { DimoEnvironment } from '../environments';
-export declare const Query: (resource: any, baseUrl: any, params: any, env: keyof typeof DimoEnvironment) => Promise<any>;
+export declare const Query: (resource: any, baseUrl: any, params: any | undefined, env: keyof typeof DimoEnvironment) => Promise<any>;
 export declare const CustomQuery: (resource: any, baseUrl: string, params?: any) => Promise<any>;

package/dist/graphql/Query.js

@@ -45,15 +45,14 @@ export const Query = async (resource, baseUrl, params = {}, env) => {
     for (const key in variables) {
         const placeholder = new RegExp(`\\$${key}\\b`, 'g');
         if (variables[key] === true) {
-            if (!params[key]) {
-                console.error(`Missing required input: ${key}`);
-                throw new DimoError({
-                    message: `Missing required input: ${key}`,
-                    statusCode: 400
-                });
+            if (params[key] === undefined || params[key] === null) {
+                // ACC-303: Replace the placeholder with null string to handle pagination
+                query = query.replace(placeholder, "null");
+            }
+            else {
+                const value = typeof params[key] === 'string' ? `"${params[key]}"` : params[key];
+                query = query.replace(placeholder, value);
             }
-            const value = typeof params[key] === 'string' ? `"${params[key]}"` : params[key];
-            query = query.replace(placeholder, value);
         }
     }
     try {

package/dist/graphql/functions/getVehiclePrivileges.d.ts

@@ -0,0 +1,6 @@
+import { DimoEnvironment } from '../../environments';
+export declare const getVehiclePrivileges: (input: {
+    headers: any;
+    tokenId: string;
+    clientId?: string;
+}, env: keyof typeof DimoEnvironment) => Promise<any>;

package/dist/graphql/functions/getVehiclePrivileges.js

@@ -0,0 +1,46 @@
+import { DIMO } from '../../dimo';
+import { DimoError } from '../../errors';
+import { paginate } from '../util/paginate';
+export const getVehiclePrivileges = async (input, env) => {
+    const sdk = new DIMO(env);
+    try {
+        const getSacds = async (after) => {
+            const response = await sdk.identity.listSacdPerVehicleTokenId({
+                tokenId: input.tokenId,
+                after
+            });
+            const sacds = response.data?.vehicle?.sacds || [];
+            const pageInfo = response.data?.vehicle?.sacds.pageInfo || { endCursor: null };
+            const totalCount = response.data?.vehicle?.sacds?.totalCount || null;
+            if (input.clientId) {
+                const matchingSacd = sacds.nodes.find((sacd) => sacd.grantee === input.clientId);
+                if (matchingSacd) {
+                    return {
+                        nodes: [matchingSacd],
+                        pageInfo: { endCursor: null },
+                        totalCount: 1
+                    };
+                }
+            }
+            return {
+                nodes: sacds,
+                pageInfo,
+                totalCount
+            };
+        };
+        if (input.clientId) {
+            const { nodes } = await getSacds(undefined);
+            if (nodes.length > 0) {
+                return nodes;
+            }
+        }
+        return await paginate(getSacds);
+    }
+    catch (error) {
+        console.error(error);
+        throw new DimoError({
+            message: `Error getting vehicle privileges: ${error.message || error}`,
+            statusCode: 400
+        });
+    }
+};

package/dist/graphql/functions/index.d.ts

@@ -1,2 +1,3 @@
+import { getVehiclePrivileges } from "./getVehiclePrivileges";
 import { getVin } from "./getVin";
-export { getVin };
+export { getVehiclePrivileges, getVin };

package/dist/graphql/functions/index.js

@@ -1,2 +1,3 @@
+import { getVehiclePrivileges } from "./getVehiclePrivileges";
 import { getVin } from "./getVin";
-export { getVin };
+export { getVehiclePrivileges, getVin };

package/dist/graphql/resources/Identity/index.d.ts

@@ -3,4 +3,3 @@ import { DimoEnvironment } from '../../../environments';
 export declare class Identity extends Resource {
     constructor(api: any, env: keyof typeof DimoEnvironment);
 }
-export declare const listVehicleDefinitionsPerAddress: (address: string, limit: number) => string;

package/dist/graphql/resources/Identity/index.js

@@ -1,4 +1,5 @@
 import { Resource } from '../../Resource';
+import { DimoConstants } from '../../../constants';
 export class Identity extends Resource {
     constructor(api, env) {
         super(api, 'Identity', env);
@@ -6,14 +7,41 @@ export class Identity extends Resource {
             query: true
         }),
             this.setQueries({
-                countDimoVehicles: {
+                getVehiclePrivileges: {
+                    method: 'FUNCTION',
+                    path: 'getVehiclePrivileges',
+                },
+                listSacdPerVehicleTokenId: {
+                    params: {
+                        tokenId: true,
+                        after: true
+                    },
                     query: `
-                { 
-                    vehicles (first:10) {
-                        totalCount,
-                    }
+            { 
+              vehicle(tokenId: $tokenId) {
+                sacds(first: ${DimoConstants.Query.PAGE_SIZE}, after: $after) {
+                  nodes {
+                    permissions
+                    grantee
+                  }
+                  totalCount
+                  pageInfo {
+                    startCursor
+                    endCursor
+                  }
                 }
-                `
+              }
+            }
+            `
+                },
+                countDimoVehicles: {
+                    query: `
+            { 
+              vehicles (first: ${DimoConstants.Query.PAGE_SIZE}) {
+                  totalCount,
+              }
+            }
+            `
                 },
                 listVehicleDefinitionsPerAddress: {
                     params: {
@@ -21,80 +49,27 @@ export class Identity extends Resource {
                         limit: true
                     },
                     query: `
-                {
-                    vehicles(filterBy: {owner: $address}, first: $limit) {
-                      nodes {
-                        aftermarketDevice {
-                            tokenId
-                            address
-                        }
-                          syntheticDevice {
-                            address
-                            tokenId
-                        }
-                        definition {
-                          make
-                          model
-                          year
-                        }
-                      }
-                    }
+            {
+              vehicles(filterBy: {owner: $address}, first: $limit) {
+                nodes {
+                  aftermarketDevice {
+                      tokenId
+                      address
+                  }
+                    syntheticDevice {
+                      address
+                      tokenId
                   }
-                `
+                  definition {
+                    make
+                    model
+                    year
+                  }
+                }
+              }
+            }
+          `
                 }
             });
     }
 }
-export const listVehicleDefinitionsPerAddress = (address, limit) => `
-{
-    vehicles(filterBy: {owner: "${address}"}, first: ${limit}) {
-      nodes {
-        aftermarketDevice {
-            tokenId
-            address
-        }
-          syntheticDevice {
-            address
-            tokenId
-        }
-        definition {
-          make
-          model
-          year
-        }
-      }
-    }
-  }
-`;
-// export const getVehicleDetailsByTokenId = (tokenId: number) => `
-// {
-//     vehicle (tokenId: ${tokenId}) {
-//       aftermarketDevice {
-//         tokenId
-//         address
-//       }
-//       syntheticDevice {
-//         address
-//         tokenId
-//       }
-//       definition {
-//         make
-//         model
-//         year
-//       }
-//     }
-//   }
-// `;
-// export const test = () => `
-// {
-//     vehicles(filterBy: {owner: "0xf9D26323Ab49179A6d57C26515B01De018553787"}, first: 10) {
-//       nodes {
-//         definition {
-//           make
-//           model
-//           year
-//         }
-//       }
-//     }
-//   }
-// `;

package/dist/graphql/util/paginate.d.ts

@@ -0,0 +1,9 @@
+export declare const paginate: <T>(fetchPage: (after: string | undefined) => Promise<{
+    nodes: {
+        nodes: T[];
+    };
+    pageInfo: {
+        endCursor: string | null;
+    };
+    totalCount: number | null;
+}>) => Promise<T[]>;