fix(errors): surface docUrl from the API error envelope on ZernioApiError

src/errors.ts

@@ -15,6 +15,7 @@ export interface ZernioErrorBody {
   type?: string;
   code?: string;
   param?: string;
+  docUrl?: string;
   platform?: string;
   platformError?: Record<string, unknown>;
   details?: Record<string, unknown>;
@@ -28,6 +29,8 @@ export class ZernioApiError extends Error {
   public readonly type?: string;
   /** The request field that caused the error, when the API names one. */
   public readonly param?: string;
+  /** Link to the documentation for this error, when the API provides one. */
+  public readonly docUrl?: string;
   /** Upstream platform, present when type is platform_error. */
   public readonly platform?: string;
   /** The upstream platform's own payload, verbatim (Meta: code, subcode, fbtrace_id). */
@@ -49,6 +52,7 @@ export class ZernioApiError extends Error {
     this.details = details;
     this.type = body?.type;
     this.param = body?.param;
+    this.docUrl = body?.docUrl;
     this.platform = body?.platform;
     this.platformError = body?.platformError;
     this.body = body;

tests/errors.test.ts

@@ -248,15 +248,17 @@ describe('parseApiError carries the whole envelope', () => {
     type: 'platform_error',
     code: 'platform_api_error',
     param: 'text',
+    docUrl: 'https://docs.zernio.com/errors/platform_api_error',
     platform: 'instagram',
     platformError: { code: 10, subcode: 2534022, fbtrace_id: 'Abc123' },
     details: { conversationId: 'c1' },
   };
 
-  it('surfaces type, param, platform and platformError', () => {
+  it('surfaces type, param, docUrl, platform and platformError', () => {
     const err = parseApiError(new Response(null, { status: 403 }), metaBody);
     expect(err.type).toBe('platform_error');
     expect(err.param).toBe('text');
+    expect(err.docUrl).toBe('https://docs.zernio.com/errors/platform_api_error');
     expect(err.platform).toBe('instagram');
     expect(err.platformError).toEqual({ code: 10, subcode: 2534022, fbtrace_id: 'Abc123' });
   });
@@ -306,6 +308,7 @@ describe('parseApiError carries the whole envelope', () => {
   it('leaves the new fields undefined when the API sent no body', () => {
     const err = parseApiError(new Response(null, { status: 500 }));
     expect(err.type).toBeUndefined();
+    expect(err.docUrl).toBeUndefined();
     expect(err.platformError).toBeUndefined();
     expect(err.statusCode).toBe(500);
   });