@collective-intelligence/external-apps-server-sdk 0.3.9 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -758,6 +758,268 @@ export type AccessMemberHoldersRequest = {
758
758
  after?: string;
759
759
  limit?: number;
760
760
  };
761
+ export type ExternalApplicationRunSource = {
762
+ documentId: string;
763
+ downloadUrl: string;
764
+ pages: Array<{
765
+ end: number;
766
+ start: number;
767
+ }>;
768
+ title: string;
769
+ versionId: string;
770
+ };
771
+ export type ExternalApplicationsGetRunSourcesErrors = {
772
+ /**
773
+ * Error
774
+ */
775
+ 400: {
776
+ correlationId: string;
777
+ error: {
778
+ code: "invalid_request";
779
+ message: string;
780
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
781
+ retryable: false;
782
+ };
783
+ };
784
+ /**
785
+ * Error
786
+ */
787
+ 401: {
788
+ correlationId: string;
789
+ error: {
790
+ code: "authentication_required";
791
+ message: string;
792
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
793
+ retryable: false;
794
+ };
795
+ };
796
+ /**
797
+ * Error
798
+ */
799
+ 403: {
800
+ correlationId: string;
801
+ error: {
802
+ code: "authorization_denied";
803
+ message: string;
804
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
805
+ retryable: false;
806
+ };
807
+ };
808
+ /**
809
+ * Error
810
+ */
811
+ 404: {
812
+ correlationId: string;
813
+ error: {
814
+ code: "operation_not_allowed";
815
+ message: string;
816
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
817
+ retryable: false;
818
+ };
819
+ } | {
820
+ correlationId: string;
821
+ error: {
822
+ code: "not_found";
823
+ message: string;
824
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
825
+ retryable: false;
826
+ };
827
+ };
828
+ /**
829
+ * Error
830
+ */
831
+ 409: {
832
+ correlationId: string;
833
+ error: {
834
+ code: "conflict";
835
+ message: string;
836
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
837
+ retryable: false;
838
+ };
839
+ } | {
840
+ correlationId: string;
841
+ error: {
842
+ code: "run_not_settled";
843
+ message: string;
844
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
845
+ retryable: true;
846
+ };
847
+ };
848
+ /**
849
+ * Error
850
+ */
851
+ 500: {
852
+ correlationId: string;
853
+ error: {
854
+ code: "internal_error";
855
+ message: string;
856
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
857
+ retryable: false;
858
+ };
859
+ };
860
+ /**
861
+ * Error
862
+ */
863
+ 503: {
864
+ correlationId: string;
865
+ error: {
866
+ code: "temporarily_unavailable";
867
+ message: string;
868
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
869
+ retryable: true;
870
+ };
871
+ };
872
+ };
873
+ export type ExternalApplicationsGetRunSourcesError = ExternalApplicationsGetRunSourcesErrors[keyof ExternalApplicationsGetRunSourcesErrors];
874
+ export type ExternalApplicationsPutRunFeedbackData = {
875
+ body: {
876
+ sentiment: "positive" | "negative";
877
+ submitterNote?: string;
878
+ };
879
+ headers: {
880
+ authorization?: string;
881
+ "x-organization-id": string;
882
+ "x-correlation-id"?: string;
883
+ "x-external-audit-issuer"?: string;
884
+ "x-external-audit-subject"?: string;
885
+ "x-external-caller-kind"?: "anonymous_visitor";
886
+ "x-external-ci-user-id"?: string;
887
+ };
888
+ path: {
889
+ runId: string;
890
+ };
891
+ query?: never;
892
+ url: "/application/v1/runs/{runId}/feedback";
893
+ };
894
+ export type ExternalApplicationsPutRunFeedbackErrors = {
895
+ /**
896
+ * Error
897
+ */
898
+ 400: {
899
+ correlationId: string;
900
+ error: {
901
+ code: "invalid_request";
902
+ message: string;
903
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
904
+ retryable: false;
905
+ };
906
+ };
907
+ /**
908
+ * Error
909
+ */
910
+ 401: {
911
+ correlationId: string;
912
+ error: {
913
+ code: "authentication_required";
914
+ message: string;
915
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
916
+ retryable: false;
917
+ };
918
+ };
919
+ /**
920
+ * Error
921
+ */
922
+ 403: {
923
+ correlationId: string;
924
+ error: {
925
+ code: "authorization_denied";
926
+ message: string;
927
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
928
+ retryable: false;
929
+ };
930
+ };
931
+ /**
932
+ * Error
933
+ */
934
+ 404: {
935
+ correlationId: string;
936
+ error: {
937
+ code: "operation_not_allowed";
938
+ message: string;
939
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
940
+ retryable: false;
941
+ };
942
+ } | {
943
+ correlationId: string;
944
+ error: {
945
+ code: "not_found";
946
+ message: string;
947
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
948
+ retryable: false;
949
+ };
950
+ };
951
+ /**
952
+ * Error
953
+ */
954
+ 409: {
955
+ correlationId: string;
956
+ error: {
957
+ code: "conflict";
958
+ message: string;
959
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
960
+ retryable: false;
961
+ };
962
+ } | {
963
+ correlationId: string;
964
+ error: {
965
+ code: "run_not_settled";
966
+ message: string;
967
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
968
+ retryable: true;
969
+ };
970
+ };
971
+ /**
972
+ * Error
973
+ */
974
+ 422: {
975
+ correlationId: string;
976
+ error: {
977
+ code: "feedback_note_required";
978
+ message: string;
979
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
980
+ retryable: false;
981
+ };
982
+ };
983
+ /**
984
+ * Error
985
+ */
986
+ 500: {
987
+ correlationId: string;
988
+ error: {
989
+ code: "internal_error";
990
+ message: string;
991
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
992
+ retryable: false;
993
+ };
994
+ };
995
+ /**
996
+ * Error
997
+ */
998
+ 503: {
999
+ correlationId: string;
1000
+ error: {
1001
+ code: "temporarily_unavailable";
1002
+ message: string;
1003
+ reason?: "users_create_forbidden" | "role_not_assignable" | "user_unavailable" | "target_inactive" | "user_not_found" | "user_not_created_by_app" | "application_unavailable" | "actor_not_allowed";
1004
+ retryable: true;
1005
+ };
1006
+ };
1007
+ };
1008
+ export type ExternalApplicationsPutRunFeedbackError = ExternalApplicationsPutRunFeedbackErrors[keyof ExternalApplicationsPutRunFeedbackErrors];
1009
+ export type ExternalApplicationsPutRunFeedbackResponses = {
1010
+ /**
1011
+ * Success
1012
+ */
1013
+ 200: {
1014
+ correlationId: string;
1015
+ result: {
1016
+ runId: string;
1017
+ sentiment: "positive" | "negative";
1018
+ submitterNote: string | null;
1019
+ };
1020
+ };
1021
+ };
1022
+ export type ExternalApplicationsPutRunFeedbackResponse = ExternalApplicationsPutRunFeedbackResponses[keyof ExternalApplicationsPutRunFeedbackResponses];
761
1023
  export type ExternalApplicationsGetContextErrors = {
762
1024
  /**
763
1025
  * Error
@@ -1536,16 +1798,36 @@ interface DurableFileUpload {
1536
1798
  fileName: string;
1537
1799
  sizeBytes: number;
1538
1800
  }
1539
- export interface ExternalApplicationServiceOperationRequest {
1801
+ /** The rating of the answer of a run: a not useful one needs a note with text. */
1802
+ export type ExternalApplicationRunFeedback = ExternalApplicationsPutRunFeedbackData["body"] & {
1803
+ runId: string;
1804
+ };
1805
+ /** Operations that only a server client invokes. */
1806
+ export type ExternalApplicationServiceOperationRequest = {
1540
1807
  input: DurableFileUpload;
1541
1808
  operationId: "files_upload";
1542
- }
1809
+ } | {
1810
+ input: {
1811
+ runId: string;
1812
+ };
1813
+ operationId: "runs_sources";
1814
+ } | {
1815
+ input: ExternalApplicationRunFeedback;
1816
+ operationId: "runs_feedback";
1817
+ };
1543
1818
  export type ExternalApplicationServiceOperationSuccess = EnvelopeSuccess<"files_upload", {
1544
1819
  storageFileId: StorageFileId;
1545
- }>;
1820
+ }> | EnvelopeSuccess<"runs_sources", {
1821
+ sources: ExternalApplicationRunSource[];
1822
+ }> | EnvelopeSuccess<"runs_feedback", ExternalApplicationsPutRunFeedbackResponse["result"]>;
1546
1823
  /** Every operation a confidential server client may invoke. */
1547
1824
  export type ExternalApplicationServerOperationRequest = ExternalApplicationOperationRequest | ExternalApplicationServiceOperationRequest;
1548
- export type ExternalApplicationOperationFailure = ExternalApplicationsGetContextError;
1825
+ /**
1826
+ * A refusal of CI; only `runs_sources` and `runs_feedback` answer
1827
+ * `run_not_settled`, and only `runs_feedback` answers
1828
+ * `feedback_note_required`.
1829
+ */
1830
+ export type ExternalApplicationOperationFailure = ExternalApplicationsGetContextError | ExternalApplicationsGetRunSourcesError | ExternalApplicationsPutRunFeedbackError;
1549
1831
  export type ExternalApplicationServerOperationId = ExternalApplicationServerOperationRequest["operationId"];
1550
1832
  export type ExternalApplicationOperationRequestFor<Id extends ExternalApplicationServerOperationId> = Extract<ExternalApplicationServerOperationRequest, {
1551
1833
  operationId: Id;
@@ -1677,6 +1959,41 @@ export type CiTag = string & Brand.Brand<"CiTag">;
1677
1959
  * `nextInvalidate` of `./next`.
1678
1960
  */
1679
1961
  export type InvalidateTags = (tags: readonly CiTag[]) => Promise<void> | void;
1962
+ /** An inclusive 1-based page range of a Document Version, such as pages 3-4. */
1963
+ export type ServerPageRange = Readonly<{
1964
+ end: number;
1965
+ start: number;
1966
+ }>;
1967
+ /**
1968
+ * One Document Version that a search of the run returned. `pages` are the
1969
+ * page ranges of its returned passages. `downloadUrl` is an Authorized Media
1970
+ * URL bound to the caller that downloads the Version; CI mints it on each
1971
+ * read, so do not store it. CI lists a Version only when that link opens.
1972
+ */
1973
+ export type ServerRunSource = Readonly<{
1974
+ documentId: string;
1975
+ downloadUrl: string;
1976
+ pages: readonly ServerPageRange[];
1977
+ title: string;
1978
+ versionId: string;
1979
+ }>;
1980
+ /** The Document Version that a Citation names. */
1981
+ export type ServerCitationTarget = Readonly<{
1982
+ documentId: string;
1983
+ versionId: string;
1984
+ }>;
1985
+ /** The Citations that a run's sources support (`kept`) and the others (`dropped`). */
1986
+ export type ServerFilteredCitations<Citation extends ServerCitationTarget> = Readonly<{
1987
+ dropped: readonly Citation[];
1988
+ kept: readonly Citation[];
1989
+ }>;
1990
+ /**
1991
+ * Splits `citations` by the Run Sources of the same run: `kept` holds each
1992
+ * Citation whose `documentId` and `versionId` pair is a source, `dropped`
1993
+ * every other Citation, both in their order. An answer cites only what a
1994
+ * search of its run returned.
1995
+ */
1996
+ export declare const filterCitations: <Citation extends ServerCitationTarget>(citations: readonly Citation[], sources: readonly ServerCitationTarget[]) => ServerFilteredCitations<Citation>;
1680
1997
  export type AuthToken = string | undefined;
1681
1998
  export interface Auth {
1682
1999
  /**
@@ -2397,7 +2714,7 @@ export type ServerRecordWriteMethod<Request> = (request: Request) => Promise<Ser
2397
2714
  export type ServerClientInvalidation = Readonly<{
2398
2715
  invalidate?: InvalidateTags;
2399
2716
  }>;
2400
- export type RunOperationId = "runs_cancel" | "runs_get" | "runs_stream";
2717
+ export type RunOperationId = "runs_cancel" | "runs_feedback" | "runs_get" | "runs_sources" | "runs_stream";
2401
2718
  export type ServerRunStatus = "accepted" | "cancelled" | "failed" | "running" | "succeeded";
2402
2719
  /**
2403
2720
  * A succeeded Agent run's result: the normal final assistant `message` and,
@@ -2436,6 +2753,20 @@ export type ServerRunEventPage = Readonly<{
2436
2753
  events: readonly ServerRunEvent[];
2437
2754
  nextCursor: string | null;
2438
2755
  }>;
2756
+ /**
2757
+ * The rating of the answer of a run that CI saved: one per person and
2758
+ * answer, the latest wins. `submitterNote` is the trimmed note of a not
2759
+ * useful rating, and `null` on a useful one.
2760
+ */
2761
+ export type ServerRunFeedback = Readonly<{
2762
+ runId: string;
2763
+ sentiment: "negative" | "positive";
2764
+ submitterNote: string | null;
2765
+ }>;
2766
+ /** The Run Sources of a settled run, in the order its searches returned them. */
2767
+ export type ServerRunSources = Readonly<{
2768
+ sources: readonly ServerRunSource[];
2769
+ }>;
2439
2770
  /**
2440
2771
  * A conversation's turns, oldest first. Each turn has the Agent's final
2441
2772
  * `message` once its run succeeded and, when the run saved one, its Agent
@@ -2559,7 +2890,32 @@ export interface ServerClient<Mode extends ServerAuthenticationMode = ServerAuth
2559
2890
  }>;
2560
2891
  readonly runs: Readonly<{
2561
2892
  cancel: ServerRunOperationMethod<"runs_cancel", ServerRun>;
2893
+ /**
2894
+ * Rates the answer of the caller's own settled run as useful
2895
+ * (`positive`) or not useful (`negative`), as the signed-in app user:
2896
+ * one rating per person and answer, the latest wins, and CI's feedback
2897
+ * monitoring links it to the run. A not useful rating needs a
2898
+ * `submitterNote` with text, or CI refuses with
2899
+ * `feedback_note_required`. Before the run settles, CI refuses with
2900
+ * `run_not_settled`. Needs `core.platform.agents` in the caller's grants.
2901
+ */
2902
+ feedback: ServerRunOperationMethod<"runs_feedback", ServerRunFeedback>;
2562
2903
  get: ServerRunOperationMethod<"runs_get", ServerRun>;
2904
+ /**
2905
+ * The Document Versions that the searches of the caller's own settled
2906
+ * run returned (Run Sources), each with its title, pages and a
2907
+ * `downloadUrl`. CI mints each `downloadUrl` for the caller on every
2908
+ * read, so read again instead of storing it. A Version is listed only
2909
+ * when its link opens: the person may read it and the app may read it
2910
+ * for its users. Only a run of an Agent that reads Documents in `user`
2911
+ * mode has Run Sources; any other run lists none. Only a signed-in app
2912
+ * user reads them: CI refuses the app's server credentials and
2913
+ * anonymous visitors with `not_found`. Before the run settles, CI
2914
+ * refuses with `run_not_settled`; wait for the run with `get`. Check the
2915
+ * Citations of the answer with `filterCitations`. Needs
2916
+ * `core.platform.agents` in the caller's grants.
2917
+ */
2918
+ sources: ServerRunOperationMethod<"runs_sources", ServerRunSources>;
2563
2919
  stream: ServerRunOperationMethod<"runs_stream", ServerRunEventPage>;
2564
2920
  }>;
2565
2921
  readonly skills: Readonly<{
package/dist/index.js CHANGED
@@ -1 +1 @@
1
- import{ServerAccessError2,MemberSessionExchangeError2,CiError2,CiTransportError2,FederatedAuthError2,serverSdkRuntime2,createServerClient2,exchangeMemberSession2,runAsApplication2,uuidV72}from"./chunks/index-d1jwmj43.js";var CiError=CiError2;var ServerAccessError=ServerAccessError2;var CiTransportError=CiTransportError2;var FederatedAuthError=FederatedAuthError2;export{CiError,CiTransportError,FederatedAuthError,MemberSessionExchangeError2 as MemberSessionExchangeError,ServerAccessError,createServerClient2 as createServerClient,exchangeMemberSession2 as exchangeMemberSession,runAsApplication2 as runAsApplication,serverSdkRuntime2 as serverSdkRuntime,uuidV72 as uuidV7};
1
+ import{ServerAccessError2,MemberSessionExchangeError2,CiError2,CiTransportError2,FederatedAuthError2,serverSdkRuntime2,createServerClient2,exchangeMemberSession2,runAsApplication2,uuidV72}from"./chunks/index-bhs224jn.js";var filterCitations=(citations,sources)=>{const returned=new Map;for(const{documentId,versionId}of sources){returned.set(documentId,(returned.get(documentId)??new Set).add(versionId))}const kept=[];const dropped=[];for(const citation of citations){const cited=returned.get(citation.documentId)?.has(citation.versionId);(cited===true?kept:dropped).push(citation)}return{dropped,kept}};var CiError=CiError2;var ServerAccessError=ServerAccessError2;var CiTransportError=CiTransportError2;var FederatedAuthError=FederatedAuthError2;export{CiError,CiTransportError,FederatedAuthError,MemberSessionExchangeError2 as MemberSessionExchangeError,ServerAccessError,createServerClient2 as createServerClient,exchangeMemberSession2 as exchangeMemberSession,filterCitations,runAsApplication2 as runAsApplication,serverSdkRuntime2 as serverSdkRuntime,uuidV72 as uuidV7};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@collective-intelligence/external-apps-server-sdk",
3
- "version": "0.3.9",
3
+ "version": "0.4.1",
4
4
  "description": "Server-side client and proxy adapters for Collective Intelligence external applications.",
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -151,8 +151,8 @@
151
151
  "test:postgres": "bun tools/test-postgres.ts src/adapters/persistence/drizzle"
152
152
  },
153
153
  "dependencies": {
154
- "@collective-intelligence/extensions-sdk": "0.3.9",
155
- "@collective-intelligence/external-apps-client-sdk": "0.3.9",
154
+ "@collective-intelligence/extensions-sdk": "0.4.1",
155
+ "@collective-intelligence/external-apps-client-sdk": "0.4.1",
156
156
  "ajv": "8.20.0",
157
157
  "ajv-formats": "3.0.1",
158
158
  "jose": "6.2.9"
@@ -251,5 +251,5 @@
251
251
  "vitest": "5.0.2",
252
252
  "zod": "4.4.3"
253
253
  },
254
- "gitHead": "56627fcab8f5db0afbfc57347d0887e6cf7f12a9"
254
+ "gitHead": "1aea8fbbdc15de6ed86458def4327d8b799d0473"
255
255
  }