@issue-reporter/core 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andy Kaprii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @issue-reporter/core
+
+Shared contracts, schemas, and formatting helpers for IssueReporter.
+
+## Install
+
+```bash
+npm install @issue-reporter/core
+```
+
+## What It Includes
+
+- request and response contracts
+- shared error codes
+- Zod-backed schemas
+- issue title/body formatting helpers
+- asset URL helpers
+
+## Smallest Useful Example
+
+```ts
+import {
+  buildIssueReportBody,
+  buildIssueReportTitle,
+  issueReportSubmissionSchema,
+} from '@issue-reporter/core';
+
+const parsed = issueReportSubmissionSchema.parse(input);
+const title = buildIssueReportTitle(parsed);
+const body = buildIssueReportBody({
+  submission: parsed,
+  screenshotUrl: 'https://cdn.example.com/report.png',
+});
+```
+
+## Limitations
+
+This package is meant to support the `@issue-reporter/react` and `@issue-reporter/fastify` packages. It is not intended as a general-purpose issue-tracking toolkit.
+
+## More
+
+- Repo docs: <https://github.com/AndyK888/IssueReporter>
+- React package: `@issue-reporter/react`
+- Fastify package: `@issue-reporter/fastify`

package/dist/assets.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizeIssueReporterAssetBaseUrl(baseUrl: string): string;
+export declare function resolveIssueReporterAssetUrl(input: {
+    assetUrl: string;
+    pageUrl: string;
+}): string;

package/dist/assets.js

@@ -0,0 +1,20 @@
+const ABSOLUTE_URL_PATTERN = /^[a-z][a-z\d+\-.]*:/i;
+export function normalizeIssueReporterAssetBaseUrl(baseUrl) {
+    return baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+}
+export function resolveIssueReporterAssetUrl(input) {
+    if (!input.assetUrl || ABSOLUTE_URL_PATTERN.test(input.assetUrl) || !input.assetUrl.startsWith('/')) {
+        return input.assetUrl;
+    }
+    try {
+        const origin = new URL(input.pageUrl).origin;
+        const publicPath = input.assetUrl.startsWith('/api/') || !input.assetUrl.startsWith('/issue-reports/')
+            ? input.assetUrl
+            : `/api${input.assetUrl}`;
+        return new URL(publicPath, `${origin}/`).toString();
+    }
+    catch {
+        return input.assetUrl;
+    }
+}
+//# sourceMappingURL=assets.js.map

package/dist/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAEpD,MAAM,UAAU,kCAAkC,CAAC,OAAe;IAChE,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,KAG5C;IACC,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACpG,OAAO,KAAK,CAAC,QAAQ,CAAC;IACxB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;QAC7C,MAAM,UAAU,GACd,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,iBAAiB,CAAC;YACjF,CAAC,CAAC,KAAK,CAAC,QAAQ;YAChB,CAAC,CAAC,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;QAE9B,OAAO,IAAI,GAAG,CAAC,UAAU,EAAE,GAAG,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC,QAAQ,CAAC;IACxB,CAAC;AACH,CAAC"}

package/dist/contracts.d.ts

@@ -0,0 +1,58 @@
+import type { Buffer } from 'node:buffer';
+export type IssueReportStatusReason = 'missing_issue_sink_config' | 'missing_storage_config' | 'disabled';
+export interface IssueReportStatus {
+    enabled: boolean;
+    reason?: IssueReportStatusReason;
+}
+export interface IssueReportViewport {
+    width: number;
+    height: number;
+}
+export interface IssueReportSubmission {
+    note: string;
+    screenshotBase64: string;
+    screenshotMimeType: 'image/png';
+    pageUrl: string;
+    route: string;
+    viewport: IssueReportViewport;
+    userAgent: string;
+    appVersion: string;
+    occurredAt: string;
+}
+export interface IssueReportResult {
+    issueNumber?: number;
+    issueUrl: string;
+    screenshotUrl: string;
+}
+export interface IssueReportAsset {
+    contentType: string;
+    body: Buffer | Uint8Array;
+}
+export interface IssueContext {
+    pageUrl: string;
+    route: string;
+    viewport: IssueReportViewport;
+    userAgent: string;
+    appVersion: string;
+    occurredAt: string;
+}
+export type IssueContextProvider = () => IssueContext | Promise<IssueContext>;
+export interface IssueSink {
+    createIssue(input: {
+        title: string;
+        body: string;
+    }): Promise<{
+        issueNumber?: number;
+        issueUrl: string;
+    }>;
+}
+export interface IssueStorage {
+    putAsset(input: {
+        asset: IssueReportAsset;
+        occurredAt: string;
+    }): Promise<{
+        key: string;
+        assetUrl: string;
+    }>;
+    getAsset(key: string): Promise<IssueReportAsset>;
+}

package/dist/contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":""}

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+export type IssueReporterErrorCode = 'disabled' | 'missing_issue_sink_config' | 'missing_storage_config' | 'missing_note' | 'note_too_long' | 'invalid_screenshot' | 'invalid_screenshot_type' | 'screenshot_too_large' | 'asset_not_found' | 'submission_failed' | 'service_unavailable';
+export interface IssueReporterErrorOptions {
+    code: IssueReporterErrorCode;
+    message: string;
+    statusCode: number;
+    cause?: unknown;
+}
+export declare class IssueReporterError extends Error {
+    readonly code: IssueReporterErrorCode;
+    readonly statusCode: number;
+    constructor(options: IssueReporterErrorOptions);
+}

package/dist/errors.js

@@ -0,0 +1,11 @@
+export class IssueReporterError extends Error {
+    code;
+    statusCode;
+    constructor(options) {
+        super(options.message, { cause: options.cause });
+        this.name = 'IssueReporterError';
+        this.code = options.code;
+        this.statusCode = options.statusCode;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAoBA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,CAAyB;IAC7B,UAAU,CAAS;IAE5B,YAAY,OAAkC;QAC5C,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IACvC,CAAC;CACF"}

package/dist/formatting.d.ts

@@ -0,0 +1,11 @@
+import type { IssueReportSubmission } from './contracts.js';
+export interface BuildIssueReportTitleInput {
+    note: string;
+    route: string;
+}
+export interface BuildIssueReportBodyInput {
+    submission: IssueReportSubmission;
+    screenshotUrl: string;
+}
+export declare function buildIssueReportTitle(input: BuildIssueReportTitleInput): string;
+export declare function buildIssueReportBody(input: BuildIssueReportBodyInput): string;

package/dist/formatting.js

@@ -0,0 +1,26 @@
+export function buildIssueReportTitle(input) {
+    const summary = input.note.trim().replace(/\s+/g, ' ').slice(0, 72) || input.route;
+    return `UI issue: ${summary}`;
+}
+export function buildIssueReportBody(input) {
+    const { submission, screenshotUrl } = input;
+    return [
+        '## User Report',
+        '',
+        submission.note.trim(),
+        '',
+        '## Screenshot',
+        '',
+        `![Reported screenshot](${screenshotUrl})`,
+        '',
+        '## Context',
+        '',
+        `- Route: \`${submission.route}\``,
+        `- Page URL: \`${submission.pageUrl}\``,
+        `- App version: \`${submission.appVersion}\``,
+        `- Viewport: \`${submission.viewport.width}x${submission.viewport.height}\``,
+        `- Submitted at: \`${submission.occurredAt}\``,
+        `- User agent: \`${submission.userAgent}\``,
+    ].join('\n');
+}
+//# sourceMappingURL=formatting.js.map

package/dist/formatting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatting.js","sourceRoot":"","sources":["../src/formatting.ts"],"names":[],"mappings":"AAYA,MAAM,UAAU,qBAAqB,CAAC,KAAiC;IACrE,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC;IACnF,OAAO,aAAa,OAAO,EAAE,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAgC;IACnE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,GAAG,KAAK,CAAC;IAE5C,OAAO;QACL,gBAAgB;QAChB,EAAE;QACF,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE;QACtB,EAAE;QACF,eAAe;QACf,EAAE;QACF,0BAA0B,aAAa,GAAG;QAC1C,EAAE;QACF,YAAY;QACZ,EAAE;QACF,cAAc,UAAU,CAAC,KAAK,IAAI;QAClC,iBAAiB,UAAU,CAAC,OAAO,IAAI;QACvC,oBAAoB,UAAU,CAAC,UAAU,IAAI;QAC7C,iBAAiB,UAAU,CAAC,QAAQ,CAAC,KAAK,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,IAAI;QAC5E,qBAAqB,UAAU,CAAC,UAAU,IAAI;QAC9C,mBAAmB,UAAU,CAAC,SAAS,IAAI;KAC5C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './assets.js';
+export * from './contracts.js';
+export * from './errors.js';
+export * from './formatting.js';
+export * from './schemas.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from './assets.js';
+export * from './contracts.js';
+export * from './errors.js';
+export * from './formatting.js';
+export * from './schemas.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC"}

package/dist/schemas.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+export declare const issueReportStatusReasonSchema: z.ZodEnum<{
+    missing_issue_sink_config: "missing_issue_sink_config";
+    missing_storage_config: "missing_storage_config";
+    disabled: "disabled";
+}>;
+export declare const issueReportStatusSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    reason: z.ZodOptional<z.ZodEnum<{
+        missing_issue_sink_config: "missing_issue_sink_config";
+        missing_storage_config: "missing_storage_config";
+        disabled: "disabled";
+    }>>;
+}, z.core.$strip>;
+export declare const issueReportViewportSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+export declare const issueReportSubmissionSchema: z.ZodObject<{
+    note: z.ZodString;
+    screenshotBase64: z.ZodString;
+    screenshotMimeType: z.ZodLiteral<"image/png">;
+    pageUrl: z.ZodString;
+    route: z.ZodString;
+    viewport: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+    userAgent: z.ZodString;
+    appVersion: z.ZodString;
+    occurredAt: z.ZodString;
+}, z.core.$strip>;
+export declare const issueReportResultSchema: z.ZodObject<{
+    issueNumber: z.ZodOptional<z.ZodNumber>;
+    issueUrl: z.ZodString;
+    screenshotUrl: z.ZodString;
+}, z.core.$strip>;

package/dist/schemas.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+export const issueReportStatusReasonSchema = z.enum([
+    'missing_issue_sink_config',
+    'missing_storage_config',
+    'disabled',
+]);
+export const issueReportStatusSchema = z.object({
+    enabled: z.boolean(),
+    reason: issueReportStatusReasonSchema.optional(),
+});
+export const issueReportViewportSchema = z.object({
+    width: z.number().finite(),
+    height: z.number().finite(),
+});
+export const issueReportSubmissionSchema = z.object({
+    note: z.string(),
+    screenshotBase64: z.string().min(1),
+    screenshotMimeType: z.literal('image/png'),
+    pageUrl: z.string().min(1),
+    route: z.string().min(1),
+    viewport: issueReportViewportSchema,
+    userAgent: z.string().min(1),
+    appVersion: z.string().min(1),
+    occurredAt: z.string().min(1),
+});
+export const issueReportResultSchema = z.object({
+    issueNumber: z.number().int().positive().optional(),
+    issueUrl: z.string().min(1),
+    screenshotUrl: z.string().min(1),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC,IAAI,CAAC;IAClD,2BAA2B;IAC3B,wBAAwB;IACxB,UAAU;CACX,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,MAAM,EAAE,6BAA6B,CAAC,QAAQ,EAAE;CACjD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE;IAC1B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE;CAC5B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,kBAAkB,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;IAC1C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,QAAQ,EAAE,yBAAyB;IACnC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC9B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACnD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACjC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@issue-reporter/core",
+  "version": "0.1.1",
+  "description": "Shared contracts, schemas, and formatting helpers for IssueReporter",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndyK888/IssueReporter.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/AndyK888/IssueReporter/tree/main/packages/core",
+  "bugs": {
+    "url": "https://github.com/AndyK888/IssueReporter/issues"
+  },
+  "keywords": [
+    "issue-reporter",
+    "bug-reporting",
+    "contracts",
+    "zod",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.10.0",
+    "npm": ">=10.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -f dist/.tsbuildinfo && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .tsbuildinfo"
+  },
+  "dependencies": {
+    "zod": "^4.1.12"
+  }
+}