Quotas

OverviewCopy Anchor Link

Quotas control how much storage each user or organization can consume. When a user or organization reaches their quota limit, further record creation or modification is blocked until storage is freed or the quota is upgraded.

Quotas are tied to accountability - the accountable entity's quota is charged for storage used by a record.

Default QuotasCopy Anchor Link

Every user receives a default storage quota when they sign up. This is configured via the DEFAULT_STORAGE_SIZE_QUOTA environment variable (in megabytes):

# Default is 500 MB if not specified
DEFAULT_STORAGE_SIZE_QUOTA=500

Organizations and groups start with zero quota by default - they must be explicitly assigned a quota through the payment system or database configuration.

Checking Quota UsageCopy Anchor Link

Use getQuota() to retrieve quota information:

// Get your own quota
const myQuota = await lr.getQuota();

console.log(myQuota.totalStorageAvailable);      // Total bytes available
console.log(myQuota.usedStorage);                // Bytes currently used
console.log(myQuota.remainingStorageAvailable);  // Bytes remaining
console.log(myQuota.isUpgraded);                 // Whether quota was upgraded via payment

// Get an organization's quota (must be member, host, or accountable)
const orgQuota = await lr.getQuota(organizationId);

Quota EnforcementCopy Anchor Link

When storage quota is exceeded:

1. Record creation is blocked - New records cannot be created
2. Record modification is blocked - Existing records cannot be updated
3. The operation fails silently - The change is not persisted

// Handle quota violations
lr.setQuotaViolationErrorHandler((response) => {
  console.log('Storage quota exceeded');
  // Show upgrade prompt or warning to user

  // If you do not throw an error here the create command
  // will not throw either.

  // You can decide not to throw and handle all violations here.
  throw new Error('Quota exceeded')
});

try {
  await lr.Record.createKeyValue({ /* large data */ });
} catch (error) {
  // This is the error you throw in the QuotaViolationErrorHandler
  // Handle quota violation
}

Upgrading QuotasCopy Anchor Link

Quotas can be upgraded through payment providers. Currently, Paddle is the only implemented payment provider.

How Quota Upgrades WorkCopy Anchor Link

1. User initiates a subscription through Paddle checkout
2. Paddle sends a webhook notification to your LinkedRecords server
3. LinkedRecords creates a quota event that increases the user's storage limit
4. The isUpgraded flag becomes true in quota responses

Paddle IntegrationCopy Anchor Link

Configure Paddle via environment variables:

PADDLE_API_KEY=your_paddle_api_key
PADDLE_API_URL=https://api.paddle.com
PADDLE_NOTIFICATION_SECRET=your_webhook_secret

Paddle webhook notifications are sent to /payment_events/paddle. The webhook payload must include:

• custom_data.nodeId - The user ID or organization ID to upgrade
• custom_data.total_storage_available in the product - The new storage limit in bytes

Example product configuration in Paddle:

{
  "custom_data": {
    "total_storage_available": "5242880000"
  }
}

Subscription EventsCopy Anchor Link

LinkedRecords handles these Paddle subscription events:

Management URLsCopy Anchor Link

The accountable party can access Paddle subscription management URLs through the quota response:

const quota = await lr.getQuota(organizationId);

// Only available to the accountable party
const urls = quota.accounteeInformation?.data?.management_urls;
if (urls) {
  console.log(urls.cancel);                // URL to cancel subscription
  console.log(urls.update_payment_method); // URL to update payment
}

Quotas and OrganizationsCopy Anchor Link

When users create resources for an organization, transfer accountability to ensure storage counts against the organization's quota:

// Personal document (counts against user's quota)
const personalDoc = await lr.Record.createKeyValue(
  { title: 'My Notes' },
  [['$it', 'isA', 'Document']]
);

// Organization document (counts against org's quota)
const orgDoc = await lr.Record.createKeyValue(
  { title: 'Project Spec' },
  [
    ['$it', 'isA', 'Document'],
    [organizationId, '$isAccountableFor', '$it'],
  ]
);

This pattern allows organizations to purchase larger quotas and have team members' work count against the shared quota rather than individual limits.

Quota ConfigurationCopy Anchor Link

Environment VariablesCopy Anchor Link

Database-Level Quota AssignmentCopy Anchor Link

For administrative purposes, quotas can be assigned directly in the database:

INSERT INTO quota_events (node_id, total_storage_available, valid_from)
VALUES ('us-user-id-here', 1073741824, NOW());  -- 1 GB

This is useful for:

• Testing quota behavior
• Granting quotas outside the payment flow
• Administrative overrides

Best PracticesCopy Anchor Link

1. Set appropriate defaults - Configure DEFAULT_STORAGE_SIZE_QUOTA based on your expected usage patterns

2. Use organization quotas - For team features, assign quotas to organizations rather than individual users

3. Handle violations gracefully - Use setQuotaViolationErrorHandler to show helpful messages when users hit limits

4. Monitor usage - Periodically check quota usage to identify users who may need upgrades

5. Transfer accountability - Ensure team resources are accountable to the organization so quota is correctly tracked