@lunch-money/v2-api-spec 2.11.1-preview.9 → 2.11.2-preview.2

package/oauth-client-logo/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared preflight and authoritative-validation policy for OAuth client logos.
+ *
+ * Client-side validation improves feedback, but API implementations must
+ * independently validate uploaded bytes and remain authoritative.
+ */
+export declare const oauthClientLogoPolicy: Readonly<{
+    readonly id: "oauth-client-logo-v1";
+    readonly acceptedMediaTypes: readonly ["image/png", "image/jpeg", "image/webp"];
+    readonly maxBytes: 1000000;
+    readonly minWidth: 200;
+    readonly minHeight: 200;
+    readonly maxWidth: 4096;
+    readonly maxHeight: 4096;
+    readonly maxPixels: 16000000;
+    readonly minAspectRatio: 0.95;
+    readonly maxAspectRatio: 1.05;
+    readonly allowAnimation: false;
+    readonly recommendations: Readonly<{
+        width: 512;
+        height: 512;
+        avoidText: true;
+        supportLightAndDarkBackgrounds: true;
+    }>;
+}>;
+export type OAuthClientLogoMediaType = typeof oauthClientLogoPolicy.acceptedMediaTypes[number];
+export type OAuthClientLogoErrorCode = 'logo_required' | 'logo_file_too_large' | 'unsupported_logo_media_type' | 'invalid_logo_image' | 'invalid_logo_dimensions' | 'invalid_logo_aspect_ratio' | 'animated_logo_not_supported' | 'logo_processing_failed';

package/oauth-client-logo/index.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oauthClientLogoPolicy = void 0;
+/**
+ * Shared preflight and authoritative-validation policy for OAuth client logos.
+ *
+ * Client-side validation improves feedback, but API implementations must
+ * independently validate uploaded bytes and remain authoritative.
+ */
+exports.oauthClientLogoPolicy = Object.freeze({
+    id: 'oauth-client-logo-v1',
+    acceptedMediaTypes: Object.freeze([
+        'image/png',
+        'image/jpeg',
+        'image/webp',
+    ]),
+    maxBytes: 1_000_000,
+    minWidth: 200,
+    minHeight: 200,
+    maxWidth: 4096,
+    maxHeight: 4096,
+    maxPixels: 16_000_000,
+    minAspectRatio: 0.95,
+    maxAspectRatio: 1.05,
+    allowAnimation: false,
+    recommendations: Object.freeze({
+        width: 512,
+        height: 512,
+        avoidText: true,
+        supportLightAndDarkBackgrounds: true,
+    }),
+});

package/oauth-scopes/catalog.js

@@ -9,30 +9,9 @@ exports.validateOAuthCatalog = validateOAuthCatalog;
 const freezeScope = (scope) => Object.freeze({ ...scope, operationIds: Object.freeze([...scope.operationIds]) });
 const freezeGroup = (group) => Object.freeze({ ...group, scopes: Object.freeze([...group.scopes]) });
 const scopeDefinitions = [
-    {
-        name: 'openid',
-        description: 'Verify your identity with Lunch Money',
-        category: 'identity',
-        operationIds: [],
-        status: 'active',
-    },
-    {
-        name: 'email',
-        description: 'View your email address and whether it has been verified',
-        category: 'identity',
-        operationIds: [],
-        status: 'active',
-    },
-    {
-        name: 'profile',
-        description: 'View your Lunch Money profile information',
-        category: 'identity',
-        operationIds: [],
-        status: 'active',
-    },
     {
         name: 'offline_access',
-        description: 'Continue accessing Lunch Money when you are not actively using the app',
+        description: 'Allow this app to maintain access without asking you to sign in and authorize it again',
         category: 'offline',
         operationIds: [],
         status: 'active',
@@ -193,7 +172,7 @@ const scopeDefinitions = [
     },
     {
         name: 'transactions:read',
-        description: 'View transactions, including split and group information and attachment metadata',
+        description: 'View transactions, including split and group information',
         category: 'api',
         operationIds: ['getAllTransactions', 'getTransactionById'],
         status: 'active',
@@ -221,7 +200,7 @@ const scopeDefinitions = [
     },
     {
         name: 'transaction_attachments:read',
-        description: 'Get download access to transaction attachments',
+        description: 'View transaction attachment metadata and get download access to attachments',
         category: 'api',
         operationIds: ['getTransactionAttachmentUrl'],
         status: 'active',
@@ -413,7 +392,7 @@ function getOAuthScopeForOperationId(operationId) {
     return scopeByOperationId.get(operationId);
 }
 const canonicalSet = (values) => [...values].sort().join('\u0000');
-const SCOPE_NAME_PATTERN = /^(?:openid|email|profile|offline_access|[a-z][a-z0-9_]*:(?:read|create|update|delete))$/;
+const SCOPE_NAME_PATTERN = /^(?:offline_access|[a-z][a-z0-9_]*:(?:read|create|update|delete))$/;
 const GROUP_ID_PATTERN = /^[a-z][a-z0-9_]*$/;
 function matchOAuthScopeGroup(scopeNames) {
     const names = new Set(scopeNames);

package/oauth-scopes/types.d.ts

@@ -7,7 +7,7 @@ export type OAuthScopeResource = 'me' | 'summary' | 'categories' | 'crypto_manua
  * Persisted and API-facing scope values remain strings so newer names can be
  * preserved and reported as unknown by consumers with an older catalog.
  */
-export type KnownOAuthScopeName = 'openid' | 'email' | 'profile' | 'offline_access' | 'me:read' | 'me:update' | 'summary:read' | 'categories:read' | 'categories:create' | 'categories:update' | 'categories:delete' | 'crypto_manual:read' | 'crypto_manual:create' | 'crypto_manual:update' | 'crypto_manual:delete' | 'crypto_synced:read' | 'crypto_synced:update' | 'balance_history:read' | 'balance_history:update' | 'balance_history:delete' | 'manual_accounts:read' | 'manual_accounts:create' | 'manual_accounts:update' | 'manual_accounts:delete' | 'plaid_accounts:read' | 'plaid_accounts:update' | 'transactions:read' | 'transactions:create' | 'transactions:update' | 'transactions:delete' | 'transaction_attachments:read' | 'transaction_attachments:create' | 'transaction_attachments:delete' | 'tags:read' | 'tags:create' | 'tags:update' | 'tags:delete' | 'recurring_items:read' | 'budgets:read' | 'budgets:update' | 'budgets:delete';
+export type KnownOAuthScopeName = 'offline_access' | 'me:read' | 'me:update' | 'summary:read' | 'categories:read' | 'categories:create' | 'categories:update' | 'categories:delete' | 'crypto_manual:read' | 'crypto_manual:create' | 'crypto_manual:update' | 'crypto_manual:delete' | 'crypto_synced:read' | 'crypto_synced:update' | 'balance_history:read' | 'balance_history:update' | 'balance_history:delete' | 'manual_accounts:read' | 'manual_accounts:create' | 'manual_accounts:update' | 'manual_accounts:delete' | 'plaid_accounts:read' | 'plaid_accounts:update' | 'transactions:read' | 'transactions:create' | 'transactions:update' | 'transactions:delete' | 'transaction_attachments:read' | 'transaction_attachments:create' | 'transaction_attachments:delete' | 'tags:read' | 'tags:create' | 'tags:update' | 'tags:delete' | 'recurring_items:read' | 'budgets:read' | 'budgets:update' | 'budgets:delete';
 export type OAuthScopeName = string;
 export interface OAuthScopeDefinition {
     readonly name: KnownOAuthScopeName;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunch-money/v2-api-spec",
-  "version": "2.11.1-preview.9",
+  "version": "2.11.2-preview.2",
   "description": "OpenAPI specification and version history for the Lunch Money v2 API",
   "main": "lunch-money-api-v2.yaml",
   "exports": {
@@ -12,6 +12,11 @@
       "require": "./oauth-scopes/index.js",
       "default": "./oauth-scopes/index.js"
     },
+    "./oauth-client-logo": {
+      "types": "./oauth-client-logo/index.d.ts",
+      "require": "./oauth-client-logo/index.js",
+      "default": "./oauth-client-logo/index.js"
+    },
     "./package.json": "./package.json",
     "./*": "./*"
   },
@@ -19,13 +24,22 @@
     "lunch-money-api-v2.yaml",
     "version-history.md",
     "oauth-scopes",
+    "oauth-client-logo",
     "README.md"
   ],
   "scripts": {
     "prepare": "husky install",
     "build:oauth-scopes": "tsc -p tsconfig.oauth-scopes.json",
+    "build:oauth-client-logo": "tsc -p tsconfig.oauth-client-logo.json",
+    "build:shared-contracts": "npm run build:oauth-scopes && npm run build:oauth-client-logo",
     "test:oauth-scopes": "npm run build:oauth-scopes && node --test test/oauth-scopes/*.test.js",
-    "prepublishOnly": "npm run build:oauth-scopes && node scripts/prep-for-publish.js",
+    "test:oauth-client-logo": "npm run build:oauth-client-logo && node --test test/oauth-client-logo/*.test.js",
+    "generate:oauth-docs": "node scripts/generate-oauth-scope-catalog.js",
+    "sync:oauth-sample": "node scripts/sync-oauth-sample-walkthrough.js",
+    "check:oauth-sample": "node scripts/sync-oauth-sample-walkthrough.js --check",
+    "validate:oauth-sample": "npm run test:oauth-docs && npm run check:oauth-sample --",
+    "test:oauth-docs": "node scripts/generate-oauth-scope-catalog.js --check && node --test test/oauth-docs/*.test.js",
+    "prepublishOnly": "npm run build:shared-contracts && node scripts/prep-for-publish.js",
     "postpublish": "node scripts/restore-readme.js",
     "publish:docs": "node scripts/publish-docs.js --tag preview",
     "publish:spec": "node scripts/publish-spec.js --tag preview",

package/version-history.md

@@ -5,12 +5,17 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
 - The minor version represents the number of main endpoints the current version of the spec supports.  For example, a version of the API that supports the /me, /categories, and /transactions endpoints would have a minor version of 3.
 - The revision number represents the number of updates since the last endpoint was added.  For example, each time changes are made to one of the existing three APIs as described above, the revision number will be bumped.
 
+## v2.11.2 - TBD
+- Add OAuth 2.0 bearer-token authentication to the v2 API, allowing applications to access Lunch Money on behalf of users who authorize them
+- Document and enforce required OAuth scopes for every v2 operation and publish the scope and scope-group catalog mapped to V2 `operationId` values. 
+  - Added a new `403` `insufficient_scope` response
+- Document the OAuth 2.0 authorization-code flow used to obtain access tokens
+- Add `include_files` query parameter to `GET /transactions/{id}`
+
 ## v2.11.1 - TBD
-- Add the OAuth scope and scope-group catalog mapped to V2 `operationId` values
 - Add `GET /me/account/settings` and `PUT /me/account/settings` for account-level settings
 - Add `GET /me/user/settings` and `PUT /me/user/settings` for user-level display and formatting preferences
 - Add `GET /me/user/account/settings` and `PUT /me/user/account/settings` for settings specific to a user and budgeting account
-from `GET /me/account/settings` and `PUT /me/account/settings` to `GET /me/user/account/settings` and `PUT /me/user/account/settings`
 - Add `include_pending_in_totals` to `GET /me/account/settings` and `PUT /me/account/settings`
 - Add `default_manual_account_id` to `GET /me/user/account/settings` and `PUT /me/user/account/settings`
 - Document `GET /budgets/settings` response schema publicly; change `budget_period_quantity` to integer