@kinotic-ai/os-api 1.4.0 → 1.5.0

package/dist/index.cjs

@@ -78,7 +78,9 @@ __export(exports_src, {
   IamUserService: () => IamUserService,
   IamUser: () => IamUser,
   GroupLoggerLevelsDescriptor: () => GroupLoggerLevelsDescriptor,
-  GitHubInstallationToken: () => GitHubInstallationToken,
+  GitHubToken: () => GitHubToken,
+  GitHubRepoToken: () => GitHubRepoToken,
+  GitHubInstallCompletion: () => GitHubInstallCompletion,
   GitHubAppInstallationService: () => GitHubAppInstallationService,
   GitHubAppInstallation: () => GitHubAppInstallation,
   FlattenedDecorator: () => FlattenedDecorator,
@@ -299,9 +301,9 @@ class Project {
   name;
   description;
   sourceOfTruth = null;
-  repoFullName = null;
-  repoId = null;
-  defaultBranch = null;
+  repoFullName;
+  repoId;
+  defaultBranch;
   repoPrivate = true;
   updated = null;
   constructor(id, applicationId, name, description) {
@@ -463,13 +465,21 @@ class GitHubAppInstallation {
   created = null;
   updated = null;
 }
-// packages/os-api/src/api/model/github/GitHubInstallationToken.ts
-class GitHubInstallationToken {
+// packages/os-api/src/api/model/github/GitHubToken.ts
+class GitHubToken {
   token = "";
   expiresAt = 0;
+}
+// packages/os-api/src/api/model/github/GitHubRepoToken.ts
+class GitHubRepoToken extends GitHubToken {
   cloneUrl = "";
   defaultBranch = "";
 }
+// packages/os-api/src/api/model/github/GitHubInstallCompletion.ts
+class GitHubInstallCompletion {
+  installation;
+  returnTo = null;
+}
 // packages/os-api/src/api/model/KinoticProjectConfig.ts
 class KinoticProjectConfig {
   name;
@@ -730,8 +740,11 @@ class GitHubAppInstallationService extends import_core9.CrudServiceProxy {
   constructor(kinotic) {
     super(kinotic.serviceProxy("org.kinotic.github.api.services.GitHubAppInstallationService"));
   }
-  startInstall() {
-    return this.serviceProxy.invoke("startInstall", []);
+  startInstall(returnTo) {
+    return this.serviceProxy.invoke("startInstall", [returnTo]);
+  }
+  completeInstall(installationId, state) {
+    return this.serviceProxy.invoke("completeInstall", [installationId, state]);
   }
   findForCurrentOrg() {
     return this.serviceProxy.invoke("findForCurrentOrg", []);

package/dist/index.d.cts

@@ -201,19 +201,18 @@ declare class Project implements Identifiable3<string> {
 	* Full name ({@code owner/repo}) of the GitHub repository backing this project.
 	* Stamped at create time by the server-side repo provisioner.
 	*/
-	repoFullName: string | null;
+	repoFullName: string;
 	/**
 	* GitHub's stable repository id. Survives renames on the GitHub side.
 	*/
-	repoId: number | null;
+	repoId: number;
 	/**
 	* Default branch of the backing repository at the time it was provisioned.
 	*/
-	defaultBranch: string | null;
+	defaultBranch: string;
 	/**
 	* Visibility chosen for the backing repository at create time. The SPA sets
-	* this on the create call; the platform passes it through to GitHub. Snapshot
-	* only — not synced back if changed on GitHub later.
+	* this before save; the platform passes it through to GitHub.
 	*/
 	repoPrivate: boolean;
 	/**
@@ -599,22 +598,38 @@ declare class GitHubAppInstallation implements Identifiable9<string> {
 	updated: number | null;
 }
 /**
-* What worker nodes receive when they ask for clone credentials. The token is a
-* short-lived GitHub installation access token scoped to a single repository with
-* {@code contents:read} permission; {@code expiresAt} is the absolute UTC instant
-* (epoch milliseconds).
+* A short-lived GitHub installation access token. Mirrors the Java
+* {@code org.kinotic.github.api.model.GitHubToken}; {@code expiresAt} is the
+* absolute UTC instant (epoch milliseconds) at which GitHub will reject the token.
 */
-declare class GitHubInstallationToken {
-	/** Bearer token to send as {@code Authorization: Bearer <token>} on git over HTTPS. */
+declare class GitHubToken {
+	/** Bearer token to send as {@code Authorization: Bearer <token>}. */
 	token: string;
-	/** Absolute expiry (epoch milliseconds). Workers should not use the token beyond this point. */
+	/** Absolute expiry (epoch milliseconds). Do not use past this point. */
 	expiresAt: number;
-	/** {@code https://github.com/<owner>/<repo>.git} for the linked repo. */
+}
+/**
+* A {@link GitHubToken} bundled with the repository-clone metadata a worker needs
+* to {@code git clone} the project's backing repo. Returned by
+* {@code GitHubProjectRepoService.issueRepoToken}.
+*/
+declare class GitHubRepoToken extends GitHubToken {
+	/** {@code https://github.com/<owner>/<repo>.git} for the project's repo. */
 	cloneUrl: string;
-	/** Default branch on the linked repo (e.g. {@code main}). */
+	/** Default branch on the repo (e.g. {@code main}). */
 	defaultBranch: string;
 }
 /**
+* Result of finalising a GitHub install round-trip. {@code returnTo} echoes what
+* the SPA staged when it called {@code startInstall(...)} and may carry query
+* params (e.g. {@code /projects?openNewProject=1}) so the destination page can
+* pick up where the user was.
+*/
+declare class GitHubInstallCompletion {
+	installation: GitHubAppInstallation;
+	returnTo: string | null;
+}
+/**
 * Configuration for a single entities path and its corresponding repository output.
 */
 type EntitiesPathConfig = {
@@ -1060,24 +1075,33 @@ declare class IamUserService extends CrudServiceProxy8<IamUser> implements IIamU
 import { CrudServiceProxy as CrudServiceProxy9, IKinotic as IKinotic12, ICrudServiceProxy as ICrudServiceProxy9 } from "@kinotic-ai/core";
 interface IGitHubAppInstallationService extends ICrudServiceProxy9<GitHubAppInstallation> {
 	/**
-	* Stages a single-use {@code state} token bound to the caller's organization in
-	* a cluster-wide store, then returns the GitHub install URL with that state
+	* Stages a single-use state token bound to the caller's organization plus the
+	* supplied returnTo, then returns the GitHub install URL with that state
 	* embedded. The SPA performs {@code window.location = url}.
-	* <p>
-	* Caller must be authenticated under {@code ORGANIZATION} scope; the org is read
-	* from the participant. The state expires after 10 minutes if unused.
+	*
+	* returnTo is echoed back from {@link completeInstall} and may carry query
+	* params (e.g. {@code /projects?openNewProject=1}) so the destination page
+	* can pick up where the user was.
+	*/
+	startInstall(returnTo: string | null): Promise<string>;
+	/**
+	* Finalises the install once GitHub has redirected the browser back to the SPA
+	* callback. Consumes the staged state, fetches the install details from GitHub,
+	* persists the {@link GitHubAppInstallation} row, and returns it along with the
+	* original intent and returnTo.
 	*/
-	startInstall(): Promise<string>;
+	completeInstall(installationId: number, state: string): Promise<GitHubInstallCompletion>;
 	/**
 	* Returns the (at-most-one) installation bound to the caller's organization, or
-	* {@code null} if GitHub is not yet linked. Drives the "linked / not linked"
-	* indicator in the org-settings UI.
+	* null if GitHub is not yet linked. Drives the "linked / not linked" indicator
+	* in the org-settings UI.
 	*/
 	findForCurrentOrg(): Promise<GitHubAppInstallation | null>;
 }
 declare class GitHubAppInstallationService extends CrudServiceProxy9<GitHubAppInstallation> implements IGitHubAppInstallationService {
 	constructor(kinotic: IKinotic12);
-	startInstall(): Promise<string>;
+	startInstall(returnTo: string | null): Promise<string>;
+	completeInstall(installationId: number, state: string): Promise<GitHubInstallCompletion>;
 	findForCurrentOrg(): Promise<GitHubAppInstallation | null>;
 }
 import { KinoticPlugin } from "@kinotic-ai/core";
@@ -1099,4 +1123,4 @@ declare const OsApiPlugin: KinoticPlugin<IOsApiExtension>;
 declare module "@kinotic-ai/core" {
 	interface KinoticSingleton extends IOsApiExtension {}
 }
-export { WorkloadStatus, WorkloadServiceProxy, Workload, VmProviderType, VmNodeStatus, VmNodeServiceProxy, VmNode, VersionDecorator, TimeReferenceDecorator, TextDecorator, TenantSelectionC3Type, TenantIdDecorator, SingleLoggerLevelsDescriptor, SignUpRequest, SignUpCompleteRequest, QueryOptionsC3Type, QueryDecorator, ProjectType, ProjectService, Project, ProgressType, PageableC3Type, PageC3Type, OsApiPlugin, OrganizationService, Organization, NotIndexedDecorator, NestedDecorator, NamedQueriesDefinitionService, NamedQueriesDefinition, MigrationService, MigrationResult, MigrationRequest, MigrationDefinition, LoggersDescriptor, LoggerLevelsDescriptor, LogManager, LogLevel, KinoticProjectConfig, InsightRequest, InsightProgress, IdDecorator, IamUserService, IamUser, IWorkloadService, IVmNodeService, IProjectService, IOsApiExtension, IOrganizationService, INamedQueriesDefinitionService, IMigrationService, ILogManager, IIamUserService, IGitHubAppInstallationService, IEntityDefinitionService, IDataInsightsService, IApplicationService, GroupLoggerLevelsDescriptor, GitHubInstallationToken, GitHubAppInstallationService, GitHubAppInstallation, FlattenedDecorator, EsIndexConfigurationDecorator, EntityDefinitionService, EntityDefinition, EntityDecorator, EntitiesPathConfig, DiscriminatorDecorator, DataInsightsService, DataInsightsComponent, AutoGeneratedIdDecorator, AuthType, ApplicationService, Application };
+export { WorkloadStatus, WorkloadServiceProxy, Workload, VmProviderType, VmNodeStatus, VmNodeServiceProxy, VmNode, VersionDecorator, TimeReferenceDecorator, TextDecorator, TenantSelectionC3Type, TenantIdDecorator, SingleLoggerLevelsDescriptor, SignUpRequest, SignUpCompleteRequest, QueryOptionsC3Type, QueryDecorator, ProjectType, ProjectService, Project, ProgressType, PageableC3Type, PageC3Type, OsApiPlugin, OrganizationService, Organization, NotIndexedDecorator, NestedDecorator, NamedQueriesDefinitionService, NamedQueriesDefinition, MigrationService, MigrationResult, MigrationRequest, MigrationDefinition, LoggersDescriptor, LoggerLevelsDescriptor, LogManager, LogLevel, KinoticProjectConfig, InsightRequest, InsightProgress, IdDecorator, IamUserService, IamUser, IWorkloadService, IVmNodeService, IProjectService, IOsApiExtension, IOrganizationService, INamedQueriesDefinitionService, IMigrationService, ILogManager, IIamUserService, IGitHubAppInstallationService, IEntityDefinitionService, IDataInsightsService, IApplicationService, GroupLoggerLevelsDescriptor, GitHubToken, GitHubRepoToken, GitHubInstallCompletion, GitHubAppInstallationService, GitHubAppInstallation, FlattenedDecorator, EsIndexConfigurationDecorator, EntityDefinitionService, EntityDefinition, EntityDecorator, EntitiesPathConfig, DiscriminatorDecorator, DataInsightsService, DataInsightsComponent, AutoGeneratedIdDecorator, AuthType, ApplicationService, Application };

package/dist/index.d.ts

@@ -201,19 +201,18 @@ declare class Project implements Identifiable3<string> {
 	* Full name ({@code owner/repo}) of the GitHub repository backing this project.
 	* Stamped at create time by the server-side repo provisioner.
 	*/
-	repoFullName: string | null;
+	repoFullName: string;
 	/**
 	* GitHub's stable repository id. Survives renames on the GitHub side.
 	*/
-	repoId: number | null;
+	repoId: number;
 	/**
 	* Default branch of the backing repository at the time it was provisioned.
 	*/
-	defaultBranch: string | null;
+	defaultBranch: string;
 	/**
 	* Visibility chosen for the backing repository at create time. The SPA sets
-	* this on the create call; the platform passes it through to GitHub. Snapshot
-	* only — not synced back if changed on GitHub later.
+	* this before save; the platform passes it through to GitHub.
 	*/
 	repoPrivate: boolean;
 	/**
@@ -599,22 +598,38 @@ declare class GitHubAppInstallation implements Identifiable9<string> {
 	updated: number | null;
 }
 /**
-* What worker nodes receive when they ask for clone credentials. The token is a
-* short-lived GitHub installation access token scoped to a single repository with
-* {@code contents:read} permission; {@code expiresAt} is the absolute UTC instant
-* (epoch milliseconds).
+* A short-lived GitHub installation access token. Mirrors the Java
+* {@code org.kinotic.github.api.model.GitHubToken}; {@code expiresAt} is the
+* absolute UTC instant (epoch milliseconds) at which GitHub will reject the token.
 */
-declare class GitHubInstallationToken {
-	/** Bearer token to send as {@code Authorization: Bearer <token>} on git over HTTPS. */
+declare class GitHubToken {
+	/** Bearer token to send as {@code Authorization: Bearer <token>}. */
 	token: string;
-	/** Absolute expiry (epoch milliseconds). Workers should not use the token beyond this point. */
+	/** Absolute expiry (epoch milliseconds). Do not use past this point. */
 	expiresAt: number;
-	/** {@code https://github.com/<owner>/<repo>.git} for the linked repo. */
+}
+/**
+* A {@link GitHubToken} bundled with the repository-clone metadata a worker needs
+* to {@code git clone} the project's backing repo. Returned by
+* {@code GitHubProjectRepoService.issueRepoToken}.
+*/
+declare class GitHubRepoToken extends GitHubToken {
+	/** {@code https://github.com/<owner>/<repo>.git} for the project's repo. */
 	cloneUrl: string;
-	/** Default branch on the linked repo (e.g. {@code main}). */
+	/** Default branch on the repo (e.g. {@code main}). */
 	defaultBranch: string;
 }
 /**
+* Result of finalising a GitHub install round-trip. {@code returnTo} echoes what
+* the SPA staged when it called {@code startInstall(...)} and may carry query
+* params (e.g. {@code /projects?openNewProject=1}) so the destination page can
+* pick up where the user was.
+*/
+declare class GitHubInstallCompletion {
+	installation: GitHubAppInstallation;
+	returnTo: string | null;
+}
+/**
 * Configuration for a single entities path and its corresponding repository output.
 */
 type EntitiesPathConfig = {
@@ -1060,24 +1075,33 @@ declare class IamUserService extends CrudServiceProxy8<IamUser> implements IIamU
 import { CrudServiceProxy as CrudServiceProxy9, IKinotic as IKinotic12, ICrudServiceProxy as ICrudServiceProxy9 } from "@kinotic-ai/core";
 interface IGitHubAppInstallationService extends ICrudServiceProxy9<GitHubAppInstallation> {
 	/**
-	* Stages a single-use {@code state} token bound to the caller's organization in
-	* a cluster-wide store, then returns the GitHub install URL with that state
+	* Stages a single-use state token bound to the caller's organization plus the
+	* supplied returnTo, then returns the GitHub install URL with that state
 	* embedded. The SPA performs {@code window.location = url}.
-	* <p>
-	* Caller must be authenticated under {@code ORGANIZATION} scope; the org is read
-	* from the participant. The state expires after 10 minutes if unused.
+	*
+	* returnTo is echoed back from {@link completeInstall} and may carry query
+	* params (e.g. {@code /projects?openNewProject=1}) so the destination page
+	* can pick up where the user was.
+	*/
+	startInstall(returnTo: string | null): Promise<string>;
+	/**
+	* Finalises the install once GitHub has redirected the browser back to the SPA
+	* callback. Consumes the staged state, fetches the install details from GitHub,
+	* persists the {@link GitHubAppInstallation} row, and returns it along with the
+	* original intent and returnTo.
 	*/
-	startInstall(): Promise<string>;
+	completeInstall(installationId: number, state: string): Promise<GitHubInstallCompletion>;
 	/**
 	* Returns the (at-most-one) installation bound to the caller's organization, or
-	* {@code null} if GitHub is not yet linked. Drives the "linked / not linked"
-	* indicator in the org-settings UI.
+	* null if GitHub is not yet linked. Drives the "linked / not linked" indicator
+	* in the org-settings UI.
 	*/
 	findForCurrentOrg(): Promise<GitHubAppInstallation | null>;
 }
 declare class GitHubAppInstallationService extends CrudServiceProxy9<GitHubAppInstallation> implements IGitHubAppInstallationService {
 	constructor(kinotic: IKinotic12);
-	startInstall(): Promise<string>;
+	startInstall(returnTo: string | null): Promise<string>;
+	completeInstall(installationId: number, state: string): Promise<GitHubInstallCompletion>;
 	findForCurrentOrg(): Promise<GitHubAppInstallation | null>;
 }
 import { KinoticPlugin } from "@kinotic-ai/core";
@@ -1099,4 +1123,4 @@ declare const OsApiPlugin: KinoticPlugin<IOsApiExtension>;
 declare module "@kinotic-ai/core" {
 	interface KinoticSingleton extends IOsApiExtension {}
 }
-export { WorkloadStatus, WorkloadServiceProxy, Workload, VmProviderType, VmNodeStatus, VmNodeServiceProxy, VmNode, VersionDecorator, TimeReferenceDecorator, TextDecorator, TenantSelectionC3Type, TenantIdDecorator, SingleLoggerLevelsDescriptor, SignUpRequest, SignUpCompleteRequest, QueryOptionsC3Type, QueryDecorator, ProjectType, ProjectService, Project, ProgressType, PageableC3Type, PageC3Type, OsApiPlugin, OrganizationService, Organization, NotIndexedDecorator, NestedDecorator, NamedQueriesDefinitionService, NamedQueriesDefinition, MigrationService, MigrationResult, MigrationRequest, MigrationDefinition, LoggersDescriptor, LoggerLevelsDescriptor, LogManager, LogLevel, KinoticProjectConfig, InsightRequest, InsightProgress, IdDecorator, IamUserService, IamUser, IWorkloadService, IVmNodeService, IProjectService, IOsApiExtension, IOrganizationService, INamedQueriesDefinitionService, IMigrationService, ILogManager, IIamUserService, IGitHubAppInstallationService, IEntityDefinitionService, IDataInsightsService, IApplicationService, GroupLoggerLevelsDescriptor, GitHubInstallationToken, GitHubAppInstallationService, GitHubAppInstallation, FlattenedDecorator, EsIndexConfigurationDecorator, EntityDefinitionService, EntityDefinition, EntityDecorator, EntitiesPathConfig, DiscriminatorDecorator, DataInsightsService, DataInsightsComponent, AutoGeneratedIdDecorator, AuthType, ApplicationService, Application };
+export { WorkloadStatus, WorkloadServiceProxy, Workload, VmProviderType, VmNodeStatus, VmNodeServiceProxy, VmNode, VersionDecorator, TimeReferenceDecorator, TextDecorator, TenantSelectionC3Type, TenantIdDecorator, SingleLoggerLevelsDescriptor, SignUpRequest, SignUpCompleteRequest, QueryOptionsC3Type, QueryDecorator, ProjectType, ProjectService, Project, ProgressType, PageableC3Type, PageC3Type, OsApiPlugin, OrganizationService, Organization, NotIndexedDecorator, NestedDecorator, NamedQueriesDefinitionService, NamedQueriesDefinition, MigrationService, MigrationResult, MigrationRequest, MigrationDefinition, LoggersDescriptor, LoggerLevelsDescriptor, LogManager, LogLevel, KinoticProjectConfig, InsightRequest, InsightProgress, IdDecorator, IamUserService, IamUser, IWorkloadService, IVmNodeService, IProjectService, IOsApiExtension, IOrganizationService, INamedQueriesDefinitionService, IMigrationService, ILogManager, IIamUserService, IGitHubAppInstallationService, IEntityDefinitionService, IDataInsightsService, IApplicationService, GroupLoggerLevelsDescriptor, GitHubToken, GitHubRepoToken, GitHubInstallCompletion, GitHubAppInstallationService, GitHubAppInstallation, FlattenedDecorator, EsIndexConfigurationDecorator, EntityDefinitionService, EntityDefinition, EntityDecorator, EntitiesPathConfig, DiscriminatorDecorator, DataInsightsService, DataInsightsComponent, AutoGeneratedIdDecorator, AuthType, ApplicationService, Application };

package/dist/index.js

@@ -202,9 +202,9 @@ class Project {
   name;
   description;
   sourceOfTruth = null;
-  repoFullName = null;
-  repoId = null;
-  defaultBranch = null;
+  repoFullName;
+  repoId;
+  defaultBranch;
   repoPrivate = true;
   updated = null;
   constructor(id, applicationId, name, description) {
@@ -366,13 +366,21 @@ class GitHubAppInstallation {
   created = null;
   updated = null;
 }
-// packages/os-api/src/api/model/github/GitHubInstallationToken.ts
-class GitHubInstallationToken {
+// packages/os-api/src/api/model/github/GitHubToken.ts
+class GitHubToken {
   token = "";
   expiresAt = 0;
+}
+// packages/os-api/src/api/model/github/GitHubRepoToken.ts
+class GitHubRepoToken extends GitHubToken {
   cloneUrl = "";
   defaultBranch = "";
 }
+// packages/os-api/src/api/model/github/GitHubInstallCompletion.ts
+class GitHubInstallCompletion {
+  installation;
+  returnTo = null;
+}
 // packages/os-api/src/api/model/KinoticProjectConfig.ts
 class KinoticProjectConfig {
   name;
@@ -633,8 +641,11 @@ class GitHubAppInstallationService extends CrudServiceProxy9 {
   constructor(kinotic) {
     super(kinotic.serviceProxy("org.kinotic.github.api.services.GitHubAppInstallationService"));
   }
-  startInstall() {
-    return this.serviceProxy.invoke("startInstall", []);
+  startInstall(returnTo) {
+    return this.serviceProxy.invoke("startInstall", [returnTo]);
+  }
+  completeInstall(installationId, state) {
+    return this.serviceProxy.invoke("completeInstall", [installationId, state]);
   }
   findForCurrentOrg() {
     return this.serviceProxy.invoke("findForCurrentOrg", []);
@@ -698,7 +709,9 @@ export {
   IamUserService,
   IamUser,
   GroupLoggerLevelsDescriptor,
-  GitHubInstallationToken,
+  GitHubToken,
+  GitHubRepoToken,
+  GitHubInstallCompletion,
   GitHubAppInstallationService,
   GitHubAppInstallation,
   FlattenedDecorator,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kinotic-ai/os-api",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "files": [
     "dist"
@@ -41,7 +41,7 @@
     "rxjs": "^7.8.2"
   },
   "devDependencies": {
-    "@kinotic-ai/core": "1.2.1",
+    "@kinotic-ai/core": "1.2.2",
     "@types/node": "^25.3.2",
     "@vitest/coverage-v8": "^4.0.18",
     "@vitest/runner": "^4.0.18",