​

Overview

• Activity content (comment text embedded in change history), feature-specific entity snapshots, and custom fields can be stored on your own infrastructure, with only necessary identifiers on Velt servers.
• Velt components automatically re-hydrate activity data in the frontend by fetching from your configured data provider.
• This gives you full control over PII while maintaining all Velt activity log features.

​

How does it work?

1. The SDK uses your configured ActivityAnnotationDataProvider to handle storage and retrieval.
2. Your data provider implements two optional methods, each of which can be supplied as either a callback function or a config endpoint URL:
   • get / getConfig: Fetches activity PII from your database and returns it for re-hydration
   • save / saveConfig: Stores PII fields stripped from the activity record before Velt writes to its backend
3. Each method is considered valid as long as it has either a callback function (get / save) or a corresponding config endpoint URL (getConfig / saveConfig).

1. The SDK strips PII from the activity record. How much is stripped depends on featureType — see What gets stripped below.
2. Your save handler receives the stripped PII (PartialActivityRecord) and stores it in your backend.
3. Velt’s backend stores the skeleton record (structural identifiers, timestamps, flags) plus any non-PII fields.

1. The SDK fetches the activity records from Velt’s backend (with PII absent).
2. The SDK runs 5 resolver passes in order: user → comment → reaction → recorder → activity. Your get handler is called during the activity pass with the activity IDs.
3. The returned PII is merged back into the activity records before they are delivered to your UI.
4. ActivityRecord.isActivityResolverUsed is set to true when PII was stripped by the resolver. Use this to show a loading state while re-hydration is pending.

​

What gets stripped

​

Built-in featureType (comment / reaction / recorder) — partial strip

​

featureType === 'custom' — wholesale removal by config

• If you list entityData or entityTargetData in fieldsToRemove, the entire field disappears from the Velt record (not field-by-field).
• If you don’t list them, they’re left untouched on the Velt record.
• fieldsToRemove is ignored for built-in feature types.

​

Universal

• displayMessage is always recomputed on the client and stored in neither DB.
• actionUser and any user objects in changes and displayMessageTemplateData are reduced to { userId } whenever a user resolver is active.
• Activity is append-only — there is no delete.

​

Implementation

​

Implementation Approaches

1. Endpoint based: Provide endpoint URLs and let the SDK handle HTTP requests
2. Function based: Implement get and save methods yourself

​

Endpoint based DataProvider

​

getConfig

• Type: ResolverEndpointConfig
• Request body format: GetActivityResolverRequest
• Response format: ResolverResponse<Record<string, PartialActivityRecord>>

const activityResolverConfig = {
  getConfig: {
    url: 'https://your-backend.com/api/velt/activity/get',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  }
};

const activityDataProvider = {
  config: activityResolverConfig
};

<VeltProvider
  apiKey='YOUR_API_KEY'
  dataProviders={{ activity: activityDataProvider }}
>
</VeltProvider>

const activityResolverConfig = {
  getConfig: {
    url: 'https://your-backend.com/api/velt/activity/get',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  }
};

const activityDataProvider = {
  config: activityResolverConfig
};

Velt.setDataProviders({ activity: activityDataProvider });

​

saveConfig

• Type: ResolverEndpointConfig
• Request body format: SaveActivityResolverRequest (the SDK sends { activity, event, metadata })
• Response format: ResolverResponse

const activityResolverConfig = {
  saveConfig: {
    url: 'https://your-backend.com/api/velt/activity/save',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  }
};

const activityDataProvider = {
  config: activityResolverConfig
};

<VeltProvider
  apiKey='YOUR_API_KEY'
  dataProviders={{ activity: activityDataProvider }}
>
</VeltProvider>

const activityResolverConfig = {
  saveConfig: {
    url: 'https://your-backend.com/api/velt/activity/save',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  }
};

const activityDataProvider = {
  config: activityResolverConfig
};

Velt.setDataProviders({ activity: activityDataProvider });

​

Endpoint based Complete Example

const activityResolverConfig = {
  getConfig: {
    url: 'https://your-backend.com/api/velt/activity/get',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  },
  saveConfig: {
    url: 'https://your-backend.com/api/velt/activity/save',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  },
  resolveTimeout: 60000,
  getRetryConfig: { retryCount: 3, retryDelay: 2000 },
  saveRetryConfig: { retryCount: 3, retryDelay: 2000, revertOnFailure: true },
  fieldsToRemove: ['customSensitiveField']
};

const activityDataProvider = {
  config: activityResolverConfig
};

<VeltProvider
  apiKey='YOUR_API_KEY'
  dataProviders={{ activity: activityDataProvider }}
>
</VeltProvider>

const activityResolverConfig = {
  getConfig: {
    url: 'https://your-backend.com/api/velt/activity/get',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  },
  saveConfig: {
    url: 'https://your-backend.com/api/velt/activity/save',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  },
  resolveTimeout: 60000,
  getRetryConfig: { retryCount: 3, retryDelay: 2000 },
  saveRetryConfig: { retryCount: 3, retryDelay: 2000, revertOnFailure: true },
  fieldsToRemove: ['customSensitiveField']
};

const activityDataProvider = {
  config: activityResolverConfig
};

Velt.setDataProviders({ activity: activityDataProvider });

​

Function based DataProvider

​

get

• Param: GetActivityResolverRequest
• Return: Promise<ResolverResponse<Record<string, PartialActivityRecord>>>

const activityDataProvider = {
  get: async (request) => {
    const response = await fetch('/api/velt/activity/get', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(request),
    });
    return await response.json();
  },
};

client.setDataProviders({ activity: activityDataProvider });

const activityDataProvider = {
  get: async (request) => {
    const response = await fetch('/api/velt/activity/get', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(request),
    });
    return await response.json();
  },
};

Velt.setDataProviders({ activity: activityDataProvider });

​

save

• Param: SaveActivityResolverRequest
• Return: Promise<ResolverResponse<undefined>>

const activityDataProvider = {
  save: async (request) => {
    const response = await fetch('/api/velt/activity/save', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(request),
    });
    return await response.json();
  },
};

client.setDataProviders({ activity: activityDataProvider });

const activityDataProvider = {
  save: async (request) => {
    const response = await fetch('/api/velt/activity/save', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(request),
    });
    return await response.json();
  },
};

Velt.setDataProviders({ activity: activityDataProvider });

​

config

• Type: ResolverConfig. Relevant properties:
  • resolveTimeout: Timeout duration (in milliseconds) for resolver operations.
  • getRetryConfig: RetryConfig. Configure retry behavior for get operations.
  • saveRetryConfig: RetryConfig. Configure retry behavior for save operations. RetryConfig is { retryCount?: number; retryDelay?: number; revertOnFailure?: boolean }. Note: revertOnFailure reverts the optimistic cache update if the save ultimately fails.
  • getConfig: ResolverEndpointConfig. Endpoint URL + headers for fetching activity PII. See Endpoint based DataProvider.
  • saveConfig: ResolverEndpointConfig. Endpoint URL + headers for saving stripped activity PII. See Endpoint based DataProvider.
  • fieldsToRemove: string[]. Top-level keys to move wholesale from the activity record to your DB. Applies only to featureType === 'custom' — built-in feature types (comment / reaction / recorder) ignore this and use the feature-aware partial strip described in What gets stripped. Listing entityData or entityTargetData moves the entire field (not field-by-field).

const activityResolverConfig = {
  resolveTimeout: 60000,
  getRetryConfig: { retryCount: 3, retryDelay: 2000 },
  saveRetryConfig: { retryCount: 3, retryDelay: 2000, revertOnFailure: true },
  fieldsToRemove: ['customSensitiveField']
};

​

Function based Complete Example

// Using API methods
client.setDataProviders({
  activity: {
    get: async (request) => {
      const response = await fetch('/api/velt/activity/get', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(request),
      });
      return await response.json();
    },
    save: async (request) => {
      const response = await fetch('/api/velt/activity/save', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(request),
      });
      return await response.json();
    },
    config: {
      resolveTimeout: 60000,
      fieldsToRemove: ['customSensitiveField'],
    },
  },
});

Velt.setDataProviders({
  activity: {
    get: async (request) => {
      const response = await fetch('/api/velt/activity/get', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(request),
      });
      return await response.json();
    },
    save: async (request) => {
      const response = await fetch('/api/velt/activity/save', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(request),
      });
      return await response.json();
    },
    config: {
      resolveTimeout: 60000,
      fieldsToRemove: ['customSensitiveField'],
    },
  },
});

​

Loading State

const activities = useAllActivities();

activities?.map((activity) => (
  activity.isActivityResolverUsed
    ? <ActivitySkeleton key={activity.id} />
    : <ActivityItem key={activity.id} activity={activity} />
));

​

Sample Data

{
  "id": "activityId",
  "metadata": {
    "apiKey": "API_KEY",
    "documentId": "DOCUMENT_ID",
    "organizationId": "ORGANIZATION_ID"
  },
  "entityData": {
    "prId": "pr-123",
    "title": "Add dark mode",
    "secretKey": "sk-abc"
  },
  "entityTargetData": {
    "commitSha": "abc123",
    "branch": "main"
  },
  "displayMessageTemplate": "{{actor.name}} deployed {{version}} to {{env}}",
  "displayMessageTemplateData": {
    "actor": { "userId": "user-1", "name": "Alice", "email": "alice@example.com" },
    "version": "v2.3.1",
    "env": "production"
  }
}

{
  "id": "activityId",
  "featureType": "custom",
  "actionType": "deployment.triggered",
  "actionUser": { "userId": "user-1" },
  "timestamp": 1773241980379,
  "metadata": {
    "apiKey": "API_KEY",
    "documentId": "INTERNAL_DOC_ID",
    "organizationId": "INTERNAL_ORG_ID",
    "clientDocumentId": "DOCUMENT_ID",
    "clientOrganizationId": "ORGANIZATION_ID"
  },
  "targetEntityId": "pr-123",
  "isActivityResolverUsed": true,
  "immutable": false
}