declastruct-github 1.0.7 → 1.1.1

package/dist/domain.objects/DeclaredGithubOwner.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeclaredGithubOwner = void 0;
+const domain_objects_1 = require("domain-objects");
+class DeclaredGithubOwner extends domain_objects_1.DomainLiteral {
+}
+exports.DeclaredGithubOwner = DeclaredGithubOwner;
+//# sourceMappingURL=DeclaredGithubOwner.js.map

package/dist/domain.objects/DeclaredGithubOwner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeclaredGithubOwner.js","sourceRoot":"","sources":["../../src/domain.objects/DeclaredGithubOwner.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AAkB/C,MAAa,mBACX,SAAQ,8BAAkC;CACT;AAFnC,kDAEmC"}

package/dist/domain.objects/DeclaredGithubRepoConfig.d.ts

@@ -27,10 +27,6 @@ export interface DeclaredGithubRepoConfig {
      * .what = whether wiki is enabled
      */
     hasWiki?: boolean;
-    /**
-     * .what = whether downloads are enabled
-     */
-    hasDownloads?: boolean;
     /**
      * .what = whether this is a template repository
      */

package/dist/domain.objects/DeclaredGithubRepoConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"DeclaredGithubRepoConfig.js","sourceRoot":"","sources":["../../src/domain.objects/DeclaredGithubRepoConfig.ts"],"names":[],"mappings":";;;AAAA,mDAA2D;AA8G3D,MAAa,wBACX,SAAQ,6BAAsC;;AADhD,4DAQC;AAJe,+BAAM,GAAG,CAAC,MAAM,CAAU,CAAC;AAC3B,+BAAM,GAAG;IACrB,IAAI,EAAE,CAAA,4BAAsC,CAAA;CAC7C,CAAC"}
+{"version":3,"file":"DeclaredGithubRepoConfig.js","sourceRoot":"","sources":["../../src/domain.objects/DeclaredGithubRepoConfig.ts"],"names":[],"mappings":";;;AAAA,mDAA2D;AAyG3D,MAAa,wBACX,SAAQ,6BAAsC;;AADhD,4DAQC;AAJe,+BAAM,GAAG,CAAC,MAAM,CAAU,CAAC;AAC3B,+BAAM,GAAG;IACrB,IAAI,EAAE,CAAA,4BAAsC,CAAA;CAC7C,CAAC"}

package/dist/domain.objects/DeclastructGithubProvider.d.ts

@@ -1,6 +1,8 @@
 import type { DeclastructDao, DeclastructProvider } from 'declastruct';
 import type { ContextLogTrail } from 'simple-log-methods';
 import type { ContextGithubApi } from './ContextGithubApi';
+import type { DeclaredGithubApp } from './DeclaredGithubApp';
+import type { DeclaredGithubAppInstallation } from './DeclaredGithubAppInstallation';
 import type { DeclaredGithubBranch } from './DeclaredGithubBranch';
 import type { DeclaredGithubBranchProtection } from './DeclaredGithubBranchProtection';
 import type { DeclaredGithubRepo } from './DeclaredGithubRepo';
@@ -14,4 +16,6 @@ export type DeclastructGithubProvider = DeclastructProvider<{
     DeclaredGithubBranch: DeclastructDao<typeof DeclaredGithubBranch, ContextGithubApi & ContextLogTrail>;
     DeclaredGithubRepoConfig: DeclastructDao<typeof DeclaredGithubRepoConfig, ContextGithubApi & ContextLogTrail>;
     DeclaredGithubBranchProtection: DeclastructDao<typeof DeclaredGithubBranchProtection, ContextGithubApi & ContextLogTrail>;
+    DeclaredGithubApp: DeclastructDao<typeof DeclaredGithubApp, ContextGithubApi & ContextLogTrail>;
+    DeclaredGithubAppInstallation: DeclastructDao<typeof DeclaredGithubAppInstallation, ContextGithubApi & ContextLogTrail>;
 }, ContextGithubApi & ContextLogTrail>;

package/dist/domain.operations/app/castToDeclaredGithubApp.d.ts

@@ -0,0 +1,12 @@
+import type { Endpoints } from '@octokit/types';
+import type { HasMetadata } from 'type-fns';
+import { DeclaredGithubApp } from '../../domain.objects/DeclaredGithubApp';
+type GithubAppResponse = Endpoints['GET /apps/{app_slug}']['response']['data'];
+/**
+ * .what = casts GitHub API app response to DeclaredGithubApp
+ * .why = transforms external API shape to our domain model with type safety and validation
+ */
+export declare const castToDeclaredGithubApp: (input: GithubAppResponse, options?: {
+    inferredPublic?: boolean;
+}) => HasMetadata<DeclaredGithubApp>;
+export {};

package/dist/domain.operations/app/castToDeclaredGithubApp.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.castToDeclaredGithubApp = void 0;
+const uni_time_1 = require("@ehmpathy/uni-time");
+const helpful_errors_1 = require("helpful-errors");
+const DeclaredGithubApp_1 = require("../../domain.objects/DeclaredGithubApp");
+const DeclaredGithubAppPermissions_1 = require("../../domain.objects/DeclaredGithubAppPermissions");
+const DeclaredGithubOwner_1 = require("../../domain.objects/DeclaredGithubOwner");
+/**
+ * .what = casts GitHub API app response to DeclaredGithubApp
+ * .why = transforms external API shape to our domain model with type safety and validation
+ */
+const castToDeclaredGithubApp = (input, options) => {
+    // fail fast if input is null
+    if (!input) {
+        helpful_errors_1.UnexpectedCodePathError.throw('app response is null', { input });
+    }
+    // extract owner from owner object
+    const ownerData = input.owner;
+    if (!ownerData) {
+        helpful_errors_1.UnexpectedCodePathError.throw('owner not found on app response', { input });
+    }
+    const ownerLogin = 'login' in ownerData ? ownerData.login : null;
+    const ownerType = 'type' in ownerData ? ownerData.type : null;
+    if (!ownerLogin || !ownerType) {
+        helpful_errors_1.UnexpectedCodePathError.throw('owner login/type not found on app response', {
+            input,
+            ownerData,
+        });
+    }
+    const owner = new DeclaredGithubOwner_1.DeclaredGithubOwner({
+        type: ownerType.toLowerCase(),
+        slug: ownerLogin,
+    });
+    // extract required fields
+    const id = input.id;
+    const slug = input.slug;
+    if (!slug) {
+        helpful_errors_1.UnexpectedCodePathError.throw('slug not found on app response', { input });
+    }
+    // cast permissions from snake_case to camelCase with nested structure
+    const permissions = castPermissions(input.permissions ?? {});
+    return DeclaredGithubApp_1.DeclaredGithubApp.as({
+        id,
+        slug,
+        owner,
+        name: input.name ?? null,
+        description: input.description
+            ? input.description
+                .split('\n')
+                .map((line) => line.trimEnd()) // normalize trailing whitespace per line
+                .join('\n')
+                .trim() // normalize leading/trailing whitespace
+            : null,
+        public: (() => {
+            // use API response if available
+            if ('public' in input)
+                return Boolean(input.public);
+            // use inferred value if provided
+            if (options?.inferredPublic !== undefined)
+                return options.inferredPublic;
+            // fail fast - never default
+            throw new helpful_errors_1.UnexpectedCodePathError('public field not in API response and no inference provided', { input });
+        })(),
+        permissions,
+        events: input.events ?? [],
+        homepageUrl: input.external_url ?? null,
+        webhookUrl: null, // not exposed in public API response
+        createdAt: input.created_at ? (0, uni_time_1.asUniDateTime)(input.created_at) : undefined,
+        updatedAt: input.updated_at ? (0, uni_time_1.asUniDateTime)(input.updated_at) : undefined,
+    });
+};
+exports.castToDeclaredGithubApp = castToDeclaredGithubApp;
+/**
+ * .what = casts GitHub API permissions object to DeclaredGithubAppPermissions
+ * .why = transforms snake_case API keys to camelCase domain model with nested repository/organization structure
+ */
+const castPermissions = (input) => {
+    // map snake_case keys to camelCase for repository permissions
+    const repositoryKeyMap = {
+        contents: 'contents',
+        pull_requests: 'pullRequests',
+        issues: 'issues',
+        actions: 'actions',
+        administration: 'administration',
+        metadata: 'metadata',
+        deployments: 'deployments',
+        checks: 'checks',
+        code_scanning: 'codeScanning',
+        secrets: 'secrets',
+        workflows: 'workflows',
+        environments: 'environments',
+        pages: 'pages',
+        packages: 'packages',
+        repository_hooks: 'hooks',
+    };
+    // map snake_case keys to camelCase for organization permissions
+    const organizationKeyMap = {
+        organization_administration: 'administration',
+        members: 'members',
+        organization_custom_properties: 'customProperties',
+        organization_user_blocking: 'userBlocking',
+        organization_hooks: 'hooks',
+        organization_secrets: 'secrets',
+        organization_projects: 'projects',
+        organization_self_hosted_runners: 'selfHostedRunners',
+    };
+    // build the repository permissions object
+    const repository = {};
+    for (const [snakeKey, value] of Object.entries(input)) {
+        const camelKey = repositoryKeyMap[snakeKey];
+        if (camelKey && value) {
+            repository[camelKey] = value;
+        }
+    }
+    // build the organization permissions object
+    const organization = {};
+    for (const [snakeKey, value] of Object.entries(input)) {
+        const camelKey = organizationKeyMap[snakeKey];
+        if (camelKey && value) {
+            organization[camelKey] = value;
+        }
+    }
+    return new DeclaredGithubAppPermissions_1.DeclaredGithubAppPermissions({
+        repository: Object.keys(repository).length > 0
+            ? repository
+            : null,
+        organization: Object.keys(organization).length > 0
+            ? organization
+            : null,
+    });
+};
+//# sourceMappingURL=castToDeclaredGithubApp.js.map

package/dist/domain.operations/app/castToDeclaredGithubApp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"castToDeclaredGithubApp.js","sourceRoot":"","sources":["../../../src/domain.operations/app/castToDeclaredGithubApp.ts"],"names":[],"mappings":"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"}

package/dist/domain.operations/app/getOneApp.d.ts

@@ -0,0 +1,15 @@
+import type { RefByUnique } from 'domain-objects';
+import type { HasMetadata, PickOne } from 'type-fns';
+import type { VisualogicContext } from 'visualogic';
+import type { ContextGithubApi } from '../../domain.objects/ContextGithubApi';
+import type { DeclaredGithubApp } from '../../domain.objects/DeclaredGithubApp';
+/**
+ * .what = gets a GitHub App by unique key
+ * .why = retrieves current state of an app from GitHub API for declarative management
+ * .note = by.primary not supported - GitHub API requires app slug or JWT auth to lookup apps
+ */
+export declare const getOneApp: (input: {
+    by: PickOne<{
+        unique: RefByUnique<typeof DeclaredGithubApp>;
+    }>;
+}, context: ContextGithubApi & VisualogicContext) => Promise<HasMetadata<DeclaredGithubApp> | null>;

package/dist/domain.operations/app/getOneApp.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOneApp = void 0;
+const rest_1 = require("@octokit/rest");
+const as_procedure_1 = require("as-procedure");
+const helpful_errors_1 = require("helpful-errors");
+const getGithubClient_1 = require("../../access/sdks/getGithubClient");
+const hasContextWithAppToken_1 = require("../context/hasContextWithAppToken");
+const hasContextWithPatToken_1 = require("../context/hasContextWithPatToken");
+const castToDeclaredGithubApp_1 = require("./castToDeclaredGithubApp");
+/**
+ * .what = checks if a GitHub App is publicly accessible via unauthenticated request
+ * .why = determines public status when API response doesn't include it
+ */
+const checkIfAppIsPublic = async (slug) => {
+    const unauthenticatedClient = new rest_1.Octokit();
+    try {
+        await unauthenticatedClient.apps.getBySlug({ app_slug: slug });
+        return true; // accessible without auth = public
+    }
+    catch {
+        return false; // not accessible without auth = private
+    }
+};
+/**
+ * .what = gets a GitHub App by unique key
+ * .why = retrieves current state of an app from GitHub API for declarative management
+ * .note = by.primary not supported - GitHub API requires app slug or JWT auth to lookup apps
+ */
+exports.getOneApp = (0, as_procedure_1.asProcedure)(async (input, context) => {
+    // get cached GitHub client
+    const github = (0, getGithubClient_1.getGithubClient)({}, context);
+    // determine app slug from input
+    if (!input.by.unique)
+        helpful_errors_1.UnexpectedCodePathError.throw('not referenced by unique. how not?', {
+            input,
+        });
+    const { slug } = input.by.unique;
+    // detect token type for inferring public field
+    const isAppToken = (0, hasContextWithAppToken_1.hasContextWithAppToken)(null, context);
+    const isPat = (0, hasContextWithPatToken_1.hasContextWithPatToken)(null, context);
+    // execute the GitHub API call
+    try {
+        const response = await github.apps.getBySlug({ app_slug: slug });
+        // infer public status based on token type
+        // - app token: if we got a response, app must be public (private apps 404 for other apps' tokens)
+        // - PAT: check via unauthenticated request (PAT can see private apps the user owns)
+        const inferredPublic = await (async () => {
+            if (isAppToken)
+                return true;
+            if (isPat)
+                return checkIfAppIsPublic(slug);
+            throw new helpful_errors_1.UnexpectedCodePathError('unsupported token type for inferring public status', { tokenPrefix: context.github.token.slice(0, 10) + '...' });
+        })();
+        return (0, castToDeclaredGithubApp_1.castToDeclaredGithubApp)(response.data, { inferredPublic });
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        // return null for 404/not found
+        if (error.message.includes('Not Found'))
+            return null;
+        // throw helpful error for all other failures
+        throw new helpful_errors_1.HelpfulError('github.getOneApp error', { cause: error });
+    }
+});
+//# sourceMappingURL=getOneApp.js.map

package/dist/domain.operations/app/getOneApp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getOneApp.js","sourceRoot":"","sources":["../../../src/domain.operations/app/getOneApp.ts"],"names":[],"mappings":";;;AAAA,wCAAwC;AACxC,+CAA2C;AAE3C,mDAAuE;AAIvE,uEAAoE;AAGpE,8EAA2E;AAC3E,8EAA2E;AAC3E,uEAAoE;AAEpE;;;GAGG;AACH,MAAM,kBAAkB,GAAG,KAAK,EAAE,IAAY,EAAoB,EAAE;IAClE,MAAM,qBAAqB,GAAG,IAAI,cAAO,EAAE,CAAC;IAC5C,IAAI,CAAC;QACH,MAAM,qBAAqB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/D,OAAO,IAAI,CAAC,CAAC,mCAAmC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC,CAAC,wCAAwC;IACxD,CAAC;AACH,CAAC,CAAC;AAEF;;;;GAIG;AACU,QAAA,SAAS,GAAG,IAAA,0BAAW,EAClC,KAAK,EACH,KAIC,EACD,OAA6C,EACG,EAAE;IAClD,2BAA2B;IAC3B,MAAM,MAAM,GAAG,IAAA,iCAAe,EAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IAE5C,gCAAgC;IAChC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM;QAClB,wCAAuB,CAAC,KAAK,CAAC,oCAAoC,EAAE;YAClE,KAAK;SACN,CAAC,CAAC;IACL,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC;IAEjC,+CAA+C;IAC/C,MAAM,UAAU,GAAG,IAAA,+CAAsB,EAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,IAAA,+CAAsB,EAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAEpD,8BAA8B;IAC9B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAEjE,0CAA0C;QAC1C,kGAAkG;QAClG,oFAAoF;QACpF,MAAM,cAAc,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE;YACvC,IAAI,UAAU;gBAAE,OAAO,IAAI,CAAC;YAC5B,IAAI,KAAK;gBAAE,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAC;YAC3C,MAAM,IAAI,wCAAuB,CAC/B,oDAAoD,EACpD,EAAE,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,EAAE,CAC3D,CAAC;QACJ,CAAC,CAAC,EAAE,CAAC;QAEL,OAAO,IAAA,iDAAuB,EAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,cAAc,EAAE,CAAC,CAAC;IACpE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;YAAE,MAAM,KAAK,CAAC;QAE3C,gCAAgC;QAChC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;YAAE,OAAO,IAAI,CAAC;QAErD,6CAA6C;QAC7C,MAAM,IAAI,6BAAY,CAAC,wBAAwB,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACrE,CAAC;AACH,CAAC,CACF,CAAC"}

package/dist/domain.operations/app/setApp.d.ts

@@ -0,0 +1,13 @@
+import type { HasMetadata, PickOne } from 'type-fns';
+import type { VisualogicContext } from 'visualogic';
+import type { ContextGithubApi } from '../../domain.objects/ContextGithubApi';
+import type { DeclaredGithubApp } from '../../domain.objects/DeclaredGithubApp';
+/**
+ * .what = sets a GitHub App: finsert or upsert
+ * .why = provides declarative interface with helpful errors since apps cannot be created/updated via API
+ * .note = GitHub Apps must be created via web UI or manifest flow; this function throws HelpfulError with actionable URLs
+ */
+export declare const setApp: (input: PickOne<{
+    finsert: DeclaredGithubApp;
+    upsert: DeclaredGithubApp;
+}>, context: ContextGithubApi & VisualogicContext) => Promise<HasMetadata<DeclaredGithubApp>>;

package/dist/domain.operations/app/setApp.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setApp = void 0;
+const as_procedure_1 = require("as-procedure");
+const helpful_errors_1 = require("helpful-errors");
+const getOneApp_1 = require("./getOneApp");
+/**
+ * .what = sets a GitHub App: finsert or upsert
+ * .why = provides declarative interface with helpful errors since apps cannot be created/updated via API
+ * .note = GitHub Apps must be created via web UI or manifest flow; this function throws HelpfulError with actionable URLs
+ */
+exports.setApp = (0, as_procedure_1.asProcedure)(async (input, context) => {
+    const desired = input.finsert ??
+        input.upsert ??
+        helpful_errors_1.UnexpectedCodePathError.throw('no app provided to setApp', { input });
+    // validate that name will cast to expected slug
+    // (GitHub auto-generates slug from name during registration)
+    const name = desired.name ?? desired.slug;
+    const expectedSlug = castNameToSlug(name);
+    if (expectedSlug !== desired.slug)
+        throw new helpful_errors_1.HelpfulError(`App name "${name}" will generate slug "${expectedSlug}", but expected slug "${desired.slug}".`, {
+            suggestion: `Either change the name to "${desired.slug}" or change the slug to "${expectedSlug}"`,
+            name,
+            expectedSlug,
+            desiredSlug: desired.slug,
+        });
+    // check whether it already exists
+    const foundBefore = await (0, getOneApp_1.getOneApp)({
+        by: {
+            unique: {
+                owner: desired.owner,
+                slug: desired.slug,
+            },
+        },
+    }, context);
+    // if it's a finsert and exists, return the found app
+    if (foundBefore && input.finsert)
+        return foundBefore;
+    // if it's an upsert and exists, throw HelpfulError with settings URL
+    if (foundBefore && input.upsert) {
+        const settingsUrl = desired.owner.type === 'organization'
+            ? `https://github.com/organizations/${desired.owner.slug}/settings/apps/${desired.slug}`
+            : `https://github.com/settings/apps/${desired.slug}`;
+        throw new helpful_errors_1.HelpfulError('GitHub Apps cannot be updated via API. Please update the app settings manually.', {
+            url: settingsUrl,
+            instructions: [
+                'Navigate to the settings URL above',
+                'Update the app permissions, events, or other settings (See the plan diff for which changes to make)',
+                'Save your changes',
+            ],
+        });
+    }
+    // app doesn't exist - provide manual creation instructions
+    const registrationUrl = desired.owner.type === 'organization'
+        ? `https://github.com/organizations/${desired.owner.slug}/settings/apps/new`
+        : `https://github.com/settings/apps/new`;
+    throw new helpful_errors_1.HelpfulError('GitHub Apps cannot be created via API. Please create the app manually.', {
+        registrationUrl,
+        instructions: [
+            `1. Navigate to: ${registrationUrl}`,
+            `2. Set the app name to: "${desired.name ?? desired.slug}"`,
+            '3. Configure permissions and events as shown in the manifest below',
+            '4. Save and generate a private key',
+        ],
+        desired,
+    });
+});
+/**
+ * .what = casts an app name to the slug GitHub will generate
+ * .why = GitHub auto-generates slugs from names during app registration
+ * .how = lowercase, replace non-alphanumeric with hyphens, collapse consecutive hyphens, trim hyphens
+ */
+const castNameToSlug = (name) => name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-') // replace non-alphanumeric sequences with single hyphen
+    .replace(/^-+|-+$/g, ''); // trim leading/trailing hyphens
+//# sourceMappingURL=setApp.js.map

package/dist/domain.operations/app/setApp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setApp.js","sourceRoot":"","sources":["../../../src/domain.operations/app/setApp.ts"],"names":[],"mappings":";;;AAAA,+CAA2C;AAC3C,mDAAuE;AAMvE,2CAAwC;AAExC;;;;GAIG;AACU,QAAA,MAAM,GAAG,IAAA,0BAAW,EAC/B,KAAK,EACH,KAGE,EACF,OAA6C,EACJ,EAAE;IAC3C,MAAM,OAAO,GACX,KAAK,CAAC,OAAO;QACb,KAAK,CAAC,MAAM;QACZ,wCAAuB,CAAC,KAAK,CAAC,2BAA2B,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAExE,gDAAgD;IAChD,6DAA6D;IAC7D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAC1C,MAAM,YAAY,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,YAAY,KAAK,OAAO,CAAC,IAAI;QAC/B,MAAM,IAAI,6BAAY,CACpB,aAAa,IAAI,yBAAyB,YAAY,yBAAyB,OAAO,CAAC,IAAI,IAAI,EAC/F;YACE,UAAU,EAAE,8BAA8B,OAAO,CAAC,IAAI,4BAA4B,YAAY,GAAG;YACjG,IAAI;YACJ,YAAY;YACZ,WAAW,EAAE,OAAO,CAAC,IAAI;SAC1B,CACF,CAAC;IAEJ,kCAAkC;IAClC,MAAM,WAAW,GAAG,MAAM,IAAA,qBAAS,EACjC;QACE,EAAE,EAAE;YACF,MAAM,EAAE;gBACN,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,IAAI,EAAE,OAAO,CAAC,IAAI;aACnB;SACF;KACF,EACD,OAAO,CACR,CAAC;IAEF,qDAAqD;IACrD,IAAI,WAAW,IAAI,KAAK,CAAC,OAAO;QAAE,OAAO,WAAW,CAAC;IAErD,qEAAqE;IACrE,IAAI,WAAW,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QAChC,MAAM,WAAW,GACf,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,cAAc;YACnC,CAAC,CAAC,oCAAoC,OAAO,CAAC,KAAK,CAAC,IAAI,kBAAkB,OAAO,CAAC,IAAI,EAAE;YACxF,CAAC,CAAC,oCAAoC,OAAO,CAAC,IAAI,EAAE,CAAC;QACzD,MAAM,IAAI,6BAAY,CACpB,iFAAiF,EACjF;YACE,GAAG,EAAE,WAAW;YAChB,YAAY,EAAE;gBACZ,oCAAoC;gBACpC,qGAAqG;gBACrG,mBAAmB;aACpB;SACF,CACF,CAAC;IACJ,CAAC;IAED,2DAA2D;IAC3D,MAAM,eAAe,GACnB,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,cAAc;QACnC,CAAC,CAAC,oCAAoC,OAAO,CAAC,KAAK,CAAC,IAAI,oBAAoB;QAC5E,CAAC,CAAC,sCAAsC,CAAC;IAE7C,MAAM,IAAI,6BAAY,CACpB,wEAAwE,EACxE;QACE,eAAe;QACf,YAAY,EAAE;YACZ,mBAAmB,eAAe,EAAE;YACpC,4BAA4B,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,GAAG;YAC3D,oEAAoE;YACpE,oCAAoC;SACrC;QACD,OAAO;KACR,CACF,CAAC;AACJ,CAAC,CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,cAAc,GAAG,CAAC,IAAY,EAAU,EAAE,CAC9C,IAAI;KACD,WAAW,EAAE;KACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,wDAAwD;KACpF,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC,gCAAgC"}

package/dist/domain.operations/appInstallation/castToDeclaredGithubAppInstallation.d.ts

@@ -0,0 +1,19 @@
+import type { Endpoints } from '@octokit/types';
+import type { HasMetadata } from 'type-fns';
+import { DeclaredGithubAppInstallation } from '../../domain.objects/DeclaredGithubAppInstallation';
+import { DeclaredGithubOwner } from '../../domain.objects/DeclaredGithubOwner';
+type GithubInstallationResponse = Endpoints['GET /orgs/{org}/installation']['response']['data'] | Endpoints['GET /users/{username}/installation']['response']['data'] | Endpoints['GET /repos/{owner}/{repo}/installation']['response']['data'] | Endpoints['GET /app/installations/{installation_id}']['response']['data'];
+/**
+ * .what = casts GitHub API installation response to DeclaredGithubAppInstallation
+ * .why = transforms external API shape to our domain model with type safety and validation
+ * .note = requires app reference to be passed in since installation response doesn't include app owner
+ */
+export declare const castToDeclaredGithubAppInstallation: (input: {
+    installation: GithubInstallationResponse;
+    app: {
+        owner: DeclaredGithubOwner;
+        slug: string;
+    };
+    repositories: string[] | null;
+}) => HasMetadata<DeclaredGithubAppInstallation>;
+export {};

package/dist/domain.operations/appInstallation/castToDeclaredGithubAppInstallation.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.castToDeclaredGithubAppInstallation = void 0;
+const uni_time_1 = require("@ehmpathy/uni-time");
+const domain_objects_1 = require("domain-objects");
+const helpful_errors_1 = require("helpful-errors");
+const DeclaredGithubApp_1 = require("../../domain.objects/DeclaredGithubApp");
+const DeclaredGithubAppInstallation_1 = require("../../domain.objects/DeclaredGithubAppInstallation");
+const DeclaredGithubOwner_1 = require("../../domain.objects/DeclaredGithubOwner");
+/**
+ * .what = casts GitHub API installation response to DeclaredGithubAppInstallation
+ * .why = transforms external API shape to our domain model with type safety and validation
+ * .note = requires app reference to be passed in since installation response doesn't include app owner
+ */
+const castToDeclaredGithubAppInstallation = (input) => {
+    const { installation, app } = input;
+    // extract account info
+    const account = installation.account;
+    if (!account)
+        helpful_errors_1.UnexpectedCodePathError.throw('installation account not found', {
+            installation,
+        });
+    // extract login from account (type narrowing)
+    const targetSlug = 'login' in account ? account.login : undefined;
+    if (!targetSlug)
+        helpful_errors_1.UnexpectedCodePathError.throw('installation account login not found', {
+            installation,
+            account,
+        });
+    // extract target type
+    const targetType = installation.target_type;
+    if (!targetType)
+        helpful_errors_1.UnexpectedCodePathError.throw('installation target_type not found', {
+            installation,
+        });
+    // compose target object
+    const target = new DeclaredGithubOwner_1.DeclaredGithubOwner({
+        type: targetType.toLowerCase(),
+        slug: targetSlug,
+    });
+    // extract repository selection
+    const repositorySelection = (installation.repository_selection ?? 'all');
+    return DeclaredGithubAppInstallation_1.DeclaredGithubAppInstallation.as({
+        id: installation.id,
+        app: app instanceof DeclaredGithubApp_1.DeclaredGithubApp
+            ? (0, domain_objects_1.refByUnique)(app)
+            : app,
+        target,
+        repositorySelection,
+        repositories: input.repositories,
+        suspended: installation.suspended_at !== null,
+        createdAt: installation.created_at
+            ? (0, uni_time_1.asUniDateTime)(installation.created_at)
+            : undefined,
+        updatedAt: installation.updated_at
+            ? (0, uni_time_1.asUniDateTime)(installation.updated_at)
+            : undefined,
+    });
+};
+exports.castToDeclaredGithubAppInstallation = castToDeclaredGithubAppInstallation;
+//# sourceMappingURL=castToDeclaredGithubAppInstallation.js.map

package/dist/domain.operations/appInstallation/castToDeclaredGithubAppInstallation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"castToDeclaredGithubAppInstallation.js","sourceRoot":"","sources":["../../../src/domain.operations/appInstallation/castToDeclaredGithubAppInstallation.ts"],"names":[],"mappings":";;;AAAA,iDAAmD;AAEnD,mDAA6C;AAC7C,mDAAyD;AAGzD,8EAA2E;AAC3E,sGAAmG;AACnG,kFAA+E;AAQ/E;;;;GAIG;AACI,MAAM,mCAAmC,GAAG,CAAC,KAInD,EAA8C,EAAE;IAC/C,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC;IAEpC,uBAAuB;IACvB,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC;IACrC,IAAI,CAAC,OAAO;QACV,wCAAuB,CAAC,KAAK,CAAC,gCAAgC,EAAE;YAC9D,YAAY;SACb,CAAC,CAAC;IAEL,8CAA8C;IAC9C,MAAM,UAAU,GAAG,OAAO,IAAI,OAAO,CAAC,CAAC,CAAE,OAAO,CAAC,KAAgB,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9E,IAAI,CAAC,UAAU;QACb,wCAAuB,CAAC,KAAK,CAAC,sCAAsC,EAAE;YACpE,YAAY;YACZ,OAAO;SACR,CAAC,CAAC;IAEL,sBAAsB;IACtB,MAAM,UAAU,GAAG,YAAY,CAAC,WAAW,CAAC;IAC5C,IAAI,CAAC,UAAU;QACb,wCAAuB,CAAC,KAAK,CAAC,oCAAoC,EAAE;YAClE,YAAY;SACb,CAAC,CAAC;IAEL,wBAAwB;IACxB,MAAM,MAAM,GAAG,IAAI,yCAAmB,CAAC;QACrC,IAAI,EAAE,UAAU,CAAC,WAAW,EAA6B;QACzD,IAAI,EAAE,UAAU;KACjB,CAAC,CAAC;IAEH,+BAA+B;IAC/B,MAAM,mBAAmB,GAAG,CAAC,YAAY,CAAC,oBAAoB,IAAI,KAAK,CAEzD,CAAC;IAEf,OAAO,6DAA6B,CAAC,EAAE,CAAC;QACtC,EAAE,EAAE,YAAY,CAAC,EAAE;QACnB,GAAG,EACD,GAAG,YAAY,qCAAiB;YAC9B,CAAC,CAAC,IAAA,4BAAW,EAA2B,GAAG,CAAC;YAC5C,CAAC,CAAC,GAAG;QACT,MAAM;QACN,mBAAmB;QACnB,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,SAAS,EAAE,YAAY,CAAC,YAAY,KAAK,IAAI;QAC7C,SAAS,EAAE,YAAY,CAAC,UAAU;YAChC,CAAC,CAAC,IAAA,wBAAa,EAAC,YAAY,CAAC,UAAU,CAAC;YACxC,CAAC,CAAC,SAAS;QACb,SAAS,EAAE,YAAY,CAAC,UAAU;YAChC,CAAC,CAAC,IAAA,wBAAa,EAAC,YAAY,CAAC,UAAU,CAAC;YACxC,CAAC,CAAC,SAAS;KACd,CAA+C,CAAC;AACnD,CAAC,CAAC;AAzDW,QAAA,mCAAmC,uCAyD9C"}

package/dist/domain.operations/appInstallation/deleteAppInstallation.d.ts

@@ -0,0 +1,11 @@
+import type { VisualogicContext } from 'visualogic';
+import type { ContextGithubApi } from '../../domain.objects/ContextGithubApi';
+import type { DeclaredGithubAppInstallation } from '../../domain.objects/DeclaredGithubAppInstallation';
+/**
+ * .what = deletes a GitHub App installation
+ * .why = provides declarative interface with helpful error since deletion requires App JWT
+ * .note = DELETE /app/installations/{id} requires App JWT which is out of scope; throws HelpfulError with uninstall URL
+ */
+export declare const deleteAppInstallation: (input: {
+    installation: DeclaredGithubAppInstallation;
+}, _context: ContextGithubApi & VisualogicContext) => Promise<never>;

package/dist/domain.operations/appInstallation/deleteAppInstallation.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteAppInstallation = void 0;
+const as_procedure_1 = require("as-procedure");
+const helpful_errors_1 = require("helpful-errors");
+/**
+ * .what = deletes a GitHub App installation
+ * .why = provides declarative interface with helpful error since deletion requires App JWT
+ * .note = DELETE /app/installations/{id} requires App JWT which is out of scope; throws HelpfulError with uninstall URL
+ */
+exports.deleteAppInstallation = (0, as_procedure_1.asProcedure)(async (input, _context) => {
+    const { installation } = input;
+    // construct the uninstall URL based on target type
+    const uninstallUrl = installation.target.type === 'organization'
+        ? `https://github.com/organizations/${installation.target.slug}/settings/installations`
+        : `https://github.com/settings/installations`;
+    throw new helpful_errors_1.HelpfulError('GitHub App installations cannot be deleted via API with a user token. Please uninstall the app manually.', {
+        uninstallUrl,
+        instructions: [
+            `1. Navigate to: ${uninstallUrl}`,
+            `2. Find the installation for app "${installation.app.slug}"`,
+            '3. Click "Configure" next to the installation',
+            '4. Scroll to the "Danger zone" section',
+            '5. Click "Uninstall" to remove the installation',
+        ],
+        note: 'Deletion via API requires an App JWT (authentication as the GitHub App itself), which is out of scope for this SDK.',
+        installation,
+    });
+});
+//# sourceMappingURL=deleteAppInstallation.js.map

package/dist/domain.operations/appInstallation/deleteAppInstallation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deleteAppInstallation.js","sourceRoot":"","sources":["../../../src/domain.operations/appInstallation/deleteAppInstallation.ts"],"names":[],"mappings":";;;AAAA,+CAA2C;AAC3C,mDAA8C;AAM9C;;;;GAIG;AACU,QAAA,qBAAqB,GAAG,IAAA,0BAAW,EAC9C,KAAK,EACH,KAEC,EACD,QAA8C,EAC9B,EAAE;IAClB,MAAM,EAAE,YAAY,EAAE,GAAG,KAAK,CAAC;IAE/B,mDAAmD;IACnD,MAAM,YAAY,GAChB,YAAY,CAAC,MAAM,CAAC,IAAI,KAAK,cAAc;QACzC,CAAC,CAAC,oCAAoC,YAAY,CAAC,MAAM,CAAC,IAAI,yBAAyB;QACvF,CAAC,CAAC,2CAA2C,CAAC;IAElD,MAAM,IAAI,6BAAY,CACpB,0GAA0G,EAC1G;QACE,YAAY;QACZ,YAAY,EAAE;YACZ,mBAAmB,YAAY,EAAE;YACjC,qCAAqC,YAAY,CAAC,GAAG,CAAC,IAAI,GAAG;YAC7D,+CAA+C;YAC/C,wCAAwC;YACxC,iDAAiD;SAClD;QACD,IAAI,EAAE,qHAAqH;QAC3H,YAAY;KACb,CACF,CAAC;AACJ,CAAC,CACF,CAAC"}

package/dist/domain.operations/appInstallation/getOneAppInstallation.d.ts

@@ -0,0 +1,15 @@
+import type { RefByUnique } from 'domain-objects';
+import type { HasMetadata } from 'type-fns';
+import type { VisualogicContext } from 'visualogic';
+import type { ContextGithubApi } from '../../domain.objects/ContextGithubApi';
+import type { DeclaredGithubAppInstallation } from '../../domain.objects/DeclaredGithubAppInstallation';
+/**
+ * .what = gets a GitHub App installation by unique key
+ * .why = retrieves current state of an installation from GitHub API for declarative management
+ * .note = lookup by primary key (installation id) is not supported - requires App JWT auth
+ */
+export declare const getOneAppInstallation: (input: {
+    by: {
+        unique: RefByUnique<typeof DeclaredGithubAppInstallation>;
+    };
+}, context: ContextGithubApi & VisualogicContext) => Promise<HasMetadata<DeclaredGithubAppInstallation> | null>;

package/dist/domain.operations/appInstallation/getOneAppInstallation.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOneAppInstallation = void 0;
+const as_procedure_1 = require("as-procedure");
+const helpful_errors_1 = require("helpful-errors");
+const getGithubClient_1 = require("../../access/sdks/getGithubClient");
+const hasContextWithAppToken_1 = require("../context/hasContextWithAppToken");
+const hasContextWithPatToken_1 = require("../context/hasContextWithPatToken");
+const castToDeclaredGithubAppInstallation_1 = require("./castToDeclaredGithubAppInstallation");
+/**
+ * .what = gets a GitHub App installation by unique key
+ * .why = retrieves current state of an installation from GitHub API for declarative management
+ * .note = lookup by primary key (installation id) is not supported - requires App JWT auth
+ */
+exports.getOneAppInstallation = (0, as_procedure_1.asProcedure)(async (input, context) => {
+    // get cached GitHub client
+    const github = (0, getGithubClient_1.getGithubClient)({}, context);
+    // handle get by unique key
+    if (input.by.unique) {
+        const { app, target } = input.by.unique;
+        // list installations for the org/user and filter by app
+        // uses GET /orgs/{org}/installations which works with PAT (admin:read scope)
+        try {
+            if (target.type === 'organization') {
+                const response = await github.orgs.listAppInstallations({
+                    org: target.slug,
+                    per_page: 100,
+                });
+                // find installation matching app slug
+                const installation = response.data.installations.find((inst) => inst.app_slug === app.slug);
+                if (!installation)
+                    return null;
+                // fetch repositories if selection is 'selected'
+                // (the list endpoint doesn't include repositories)
+                let repositories = null;
+                if (installation.repository_selection === 'selected') {
+                    // detect token type
+                    const isPatToken = (0, hasContextWithPatToken_1.hasContextWithPatToken)(null, context);
+                    const isAppToken = (0, hasContextWithAppToken_1.hasContextWithAppToken)(null, context);
+                    // fail fast on unknown token type
+                    if (!isPatToken && !isAppToken) {
+                        throw new helpful_errors_1.HelpfulError('Unknown token type. Expected PAT (ghp_* or github_pat_*) or installation token (ghs_*).', { tokenPrefix: context.github.token.slice(0, 10) + '...' });
+                    }
+                    // PAT: GET /user/installations/{id}/repositories
+                    if (isPatToken) {
+                        const reposResponse = await github.apps.listInstallationReposForAuthenticatedUser({
+                            installation_id: installation.id,
+                            per_page: 100,
+                        });
+                        repositories = reposResponse.data.repositories.map((r) => r.name);
+                    }
+                    // installation token: GET /installation/repositories
+                    if (isAppToken) {
+                        const reposResponse = await github.apps.listReposAccessibleToInstallation({
+                            per_page: 100,
+                        });
+                        repositories = reposResponse.data.repositories.map((r) => r.name);
+                    }
+                    // fail fast if repositories weren't fetched
+                    if (repositories === null) {
+                        throw new helpful_errors_1.UnexpectedCodePathError('repositories not fetched for selected installation', { isPatToken, isAppToken, installation_id: installation.id });
+                    }
+                }
+                return (0, castToDeclaredGithubAppInstallation_1.castToDeclaredGithubAppInstallation)({
+                    installation,
+                    app,
+                    repositories,
+                });
+            }
+            // for User targets, there's no PAT-accessible endpoint
+            if (target.type === 'user') {
+                throw new helpful_errors_1.HelpfulError('User installations are not supported. GitHub API has no PAT-accessible endpoint to read user installations.', { target });
+            }
+            // for unsupported target.type, fail fast
+            throw new helpful_errors_1.UnexpectedCodePathError('unsupported target.type', { input });
+        }
+        catch (error) {
+            if (!(error instanceof Error))
+                throw error;
+            if (error.message.includes('Not Found'))
+                return null;
+            throw new helpful_errors_1.HelpfulError('github.getOneAppInstallation.byUnique error', {
+                cause: error,
+            });
+        }
+    }
+    // no valid key provided
+    helpful_errors_1.UnexpectedCodePathError.throw('getOneAppInstallation requires by.unique', {
+        input,
+    });
+});
+//# sourceMappingURL=getOneAppInstallation.js.map