Merge pull request #543 from abraham/async-refresh

Add Mastodon-Async-Refresh header

Author: abraham

dist/schema.json

@@ -23417,6 +23417,12 @@
                   "type": "string",
                   "format": "date-time"
                 }
+              },
+              "Mastodon-Async-Refresh": {
+                "description": "Indicates an async refresh is in progress. Format: id=\"<string>\", retry=<int>, result_count=<int>. The retry value indicates seconds to wait before retrying. The result_count is optional and indicates results already fetched.",
+                "schema": {
+                  "type": "string"
+                }
               }
             },
             "content": {

src/__tests__/generators/OpenAPIGenerator.asyncRefreshHeader.test.ts

@@ -0,0 +1,167 @@
+import { OpenAPIGenerator } from '../../generators/OpenAPIGenerator';
+import { ApiMethodsFile } from '../../interfaces/ApiMethodsFile';
+
+describe('OpenAPIGenerator - Mastodon-Async-Refresh Header', () => {
+  let generator: OpenAPIGenerator;
+
+  beforeEach(() => {
+    generator = new OpenAPIGenerator();
+  });
+
+  it('should add Mastodon-Async-Refresh header to status context endpoint', () => {
+    const methodFiles: ApiMethodsFile[] = [
+      {
+        name: 'statuses',
+        description: 'Status methods',
+        methods: [
+          {
+            name: 'Get parent and child statuses in context',
+            httpMethod: 'GET',
+            endpoint: '/api/v1/statuses/:id/context',
+            description:
+              'View statuses above and below this status in the thread.',
+            returns: 'Context',
+          },
+        ],
+      },
+    ];
+
+    const spec = generator.generateSchema([], methodFiles);
+
+    // Find the status context endpoint
+    const contextPath = '/api/v1/statuses/{id}/context';
+    expect(spec.paths[contextPath]).toBeDefined();
+
+    const getOperation = spec.paths[contextPath]?.get;
+    expect(getOperation).toBeDefined();
+    expect(getOperation?.operationId).toBe('getStatusContext');
+
+    // Check that 200 response has headers
+    const response200 = getOperation?.responses['200'];
+    expect(response200).toBeDefined();
+    expect(response200?.headers).toBeDefined();
+
+    // Verify rate limit headers are present
+    expect(response200?.headers?.['X-RateLimit-Limit']).toBeDefined();
+    expect(response200?.headers?.['X-RateLimit-Remaining']).toBeDefined();
+    expect(response200?.headers?.['X-RateLimit-Reset']).toBeDefined();
+
+    // Verify Mastodon-Async-Refresh header is present
+    expect(response200?.headers?.['Mastodon-Async-Refresh']).toBeDefined();
+    expect(
+      response200?.headers?.['Mastodon-Async-Refresh']?.description
+    ).toContain('async refresh');
+    expect(
+      response200?.headers?.['Mastodon-Async-Refresh']?.description
+    ).toContain('retry');
+    expect(
+      response200?.headers?.['Mastodon-Async-Refresh']?.description
+    ).toContain('result_count');
+    expect(response200?.headers?.['Mastodon-Async-Refresh']?.schema.type).toBe(
+      'string'
+    );
+  });
+
+  it('should not add Mastodon-Async-Refresh header to other status endpoints', () => {
+    const methodFiles: ApiMethodsFile[] = [
+      {
+        name: 'statuses',
+        description: 'Status methods',
+        methods: [
+          {
+            name: 'View specific status',
+            httpMethod: 'GET',
+            endpoint: '/api/v1/statuses/:id',
+            description: 'View information about a status.',
+            returns: 'Status',
+          },
+          {
+            name: 'Favourite status',
+            httpMethod: 'POST',
+            endpoint: '/api/v1/statuses/:id/favourite',
+            description: 'Add a status to your favourites list.',
+            returns: 'Status',
+          },
+          {
+            name: 'Reblog status',
+            httpMethod: 'POST',
+            endpoint: '/api/v1/statuses/:id/reblog',
+            description: 'Reshare a status.',
+            returns: 'Status',
+          },
+          {
+            name: 'Bookmark status',
+            httpMethod: 'POST',
+            endpoint: '/api/v1/statuses/:id/bookmark',
+            description: 'Bookmark a status.',
+            returns: 'Status',
+          },
+        ],
+      },
+    ];
+
+    const spec = generator.generateSchema([], methodFiles);
+
+    // Check that other status endpoints don't have the header
+    const otherEndpoints = [
+      '/api/v1/statuses/{id}',
+      '/api/v1/statuses/{id}/favourite',
+      '/api/v1/statuses/{id}/reblog',
+      '/api/v1/statuses/{id}/bookmark',
+    ];
+
+    for (const endpoint of otherEndpoints) {
+      if (spec.paths[endpoint]) {
+        const operations = spec.paths[endpoint];
+        for (const operation of Object.values(operations)) {
+          if (
+            operation &&
+            typeof operation === 'object' &&
+            'responses' in operation
+          ) {
+            const op = operation as {
+              responses: Record<string, { headers?: Record<string, unknown> }>;
+            };
+            if (op.responses?.['200']?.headers) {
+              expect(
+                op.responses['200'].headers['Mastodon-Async-Refresh']
+              ).toBeUndefined();
+            }
+          }
+        }
+      }
+    }
+  });
+
+  it('should include correct format description in Mastodon-Async-Refresh header', () => {
+    const methodFiles: ApiMethodsFile[] = [
+      {
+        name: 'statuses',
+        description: 'Status methods',
+        methods: [
+          {
+            name: 'Get parent and child statuses in context',
+            httpMethod: 'GET',
+            endpoint: '/api/v1/statuses/:id/context',
+            description:
+              'View statuses above and below this status in the thread.',
+            returns: 'Context',
+          },
+        ],
+      },
+    ];
+
+    const spec = generator.generateSchema([], methodFiles);
+
+    const contextPath = '/api/v1/statuses/{id}/context';
+    const getOperation = spec.paths[contextPath]?.get;
+    const asyncRefreshHeader =
+      getOperation?.responses['200']?.headers?.['Mastodon-Async-Refresh'];
+
+    expect(asyncRefreshHeader?.description).toContain('id=');
+    expect(asyncRefreshHeader?.description).toContain('retry=');
+    expect(asyncRefreshHeader?.description).toContain('result_count=');
+    expect(asyncRefreshHeader?.description).toContain('<string>');
+    expect(asyncRefreshHeader?.description).toContain('<int>');
+  });
+});

src/generators/MethodConverter.ts

@@ -628,6 +628,29 @@ class MethodConverter {
     };
   }
 
+  /**
+   * Check if a method is the status context endpoint
+   */
+  private isStatusContextMethod(method: ApiMethod): boolean {
+    return (
+      method.httpMethod === 'GET' &&
+      method.endpoint === '/api/v1/statuses/:id/context'
+    );
+  }
+
+  /**
+   * Generate Mastodon-Async-Refresh header for status context endpoint
+   */
+  private generateAsyncRefreshHeader(): OpenAPIHeader {
+    return {
+      description:
+        'Indicates an async refresh is in progress. Format: id="<string>", retry=<int>, result_count=<int>. The retry value indicates seconds to wait before retrying. The result_count is optional and indicates results already fetched.',
+      schema: {
+        type: 'string',
+      },
+    };
+  }
+
   /**
    * Generate combined headers for 2xx responses (rate limit + Link if applicable)
    */
@@ -643,6 +666,11 @@ class MethodConverter {
       headers['Link'] = this.generateLinkHeader();
     }
 
+    // Add Mastodon-Async-Refresh header for status context endpoint
+    if (this.isStatusContextMethod(method)) {
+      headers['Mastodon-Async-Refresh'] = this.generateAsyncRefreshHeader();
+    }
+
     return headers;
   }