@numericoach/gskills-admin-cli 0.1.2 → 0.1.4

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/README.md CHANGED
@@ -38,6 +38,21 @@ gskills-admin cache invalidate --instance <instanceId> --scope pages --languages
38
38
  gskills-admin cache invalidate --instance <instanceId> --scope menu-bundle --yes --output json
39
39
  ```
40
40
 
41
+ Operational helpers are available for the admin-only flows agents should not improvise:
42
+
43
+ ```bash
44
+ gskills-admin feedback send-reply <feedbackId> --subject "GSkills - ..." --body "Bonjour..." --dry-run --output json
45
+ gskills-admin access grant --user <userId> --type DEFAULT --dry-run --output json
46
+ gskills-admin instances create-plan --output json
47
+ gskills-admin instances create --data '{"name":"Client","URL":"client","licenceType":"STARTER","tokensAllowed":50}' --dry-run --output json
48
+ gskills-admin entities list --instance <instanceId> --output json
49
+ gskills-admin entities set-page-visibility --instance <instanceId> --page <pageId> --entity-ids google-group:team@example.com --dry-run --output json
50
+ gskills-admin org-units-sync google --instance <instanceId> --yes --output json
51
+ gskills-admin ambassadors label --instance <instanceId> --language fr --output json
52
+ ```
53
+
54
+ Raw project and analytics data can be read through resources such as `project-data`, `ticket-sla-rules`, `analytics`, `quiz-attempts`, `user-paths`, `chromebook-progress`, and `user-learning-paths`.
55
+
41
56
  ## Agent skill
42
57
 
43
58
  Install the bundled skill so AI agents know the auth model, resource map, output modes, sync workflow, and content-authoring standards.
@@ -405,6 +405,33 @@ var resources = [
405
405
  aliases: ["instance-project-data"],
406
406
  defaultFields: ["id", "instanceId", "clientAdminEmail", "clientType", "goLiveAt", "updatedAt"]
407
407
  },
408
+ {
409
+ name: "project-contacts",
410
+ delegate: "instanceClientContact",
411
+ label: "Project contacts",
412
+ aliases: ["project-contact", "client-contacts", "additional-contacts"],
413
+ defaultFields: ["id", "instanceProjectDataId", "email", "firstName", "lastName", "jobTitle", "order", "updatedAt"],
414
+ instanceField: null,
415
+ dangerousDelete: true
416
+ },
417
+ {
418
+ name: "ticket-sla-rules",
419
+ delegate: "instanceTicketSlaRule",
420
+ label: "Ticket SLA rules",
421
+ aliases: ["sla-rules", "ticket-sla-rule"],
422
+ defaultFields: ["id", "instanceProjectDataId", "label", "ackTargetValue", "ackTargetUnit", "resolutionTargetValue", "resolutionTargetUnit", "order", "updatedAt"],
423
+ instanceField: null,
424
+ dangerousDelete: true
425
+ },
426
+ {
427
+ name: "ticket-sla-contacts",
428
+ delegate: "instanceTicketSlaContact",
429
+ label: "Ticket SLA contacts",
430
+ aliases: ["sla-contacts", "ticket-sla-contact"],
431
+ defaultFields: ["id", "instanceProjectDataId", "email", "firstName", "lastName", "jobTitle", "order", "updatedAt"],
432
+ instanceField: null,
433
+ dangerousDelete: true
434
+ },
408
435
  {
409
436
  name: "instances",
410
437
  delegate: "instance",
@@ -445,6 +472,41 @@ var resources = [
445
472
  aliases: ["feedback"],
446
473
  defaultFields: ["id", "instanceId", "userId", "type", "status", "priority", "createdAt", "updatedAt"]
447
474
  },
475
+ {
476
+ name: "feedback-replies",
477
+ delegate: "feedbackReply",
478
+ label: "Feedback replies",
479
+ aliases: ["feedback-reply", "replies"],
480
+ defaultFields: ["id", "feedbackId", "authorId", "subjectFr", "targetLang", "createdAt"],
481
+ instanceField: null,
482
+ dangerousDelete: true
483
+ },
484
+ {
485
+ name: "feedback-assignees",
486
+ delegate: "feedbackAssignee",
487
+ label: "Feedback assignees",
488
+ aliases: ["feedback-assignee"],
489
+ defaultFields: ["id", "feedbackId", "userId", "assignedAt"],
490
+ instanceField: null,
491
+ dangerousDelete: true
492
+ },
493
+ {
494
+ name: "feedback-claim-notifications",
495
+ delegate: "feedbackClaimNotification",
496
+ label: "Feedback claim notifications",
497
+ aliases: ["claim-notifications", "feedback-emails"],
498
+ defaultFields: ["id", "feedbackId", "authorId", "recipientEmail", "subject", "source", "createdAt"],
499
+ instanceField: null
500
+ },
501
+ {
502
+ name: "ambassadors",
503
+ delegate: "ambassadorInstance",
504
+ label: "Ambassadors",
505
+ aliases: ["ambassador", "champions", "champion", "experts", "expert"],
506
+ defaultFields: ["id", "userId", "active", "descriptionAmbassador", "contactContent", "createdOn"],
507
+ instanceField: null,
508
+ dangerousDelete: true
509
+ },
448
510
  {
449
511
  name: "tags",
450
512
  delegate: "tag",
@@ -496,6 +558,48 @@ var resources = [
496
558
  aliases: ["feature-flag", "flags"],
497
559
  defaultFields: ["id", "featureKey", "targetType", "targetId", "active", "variant", "updatedAt"]
498
560
  },
561
+ {
562
+ name: "groups",
563
+ delegate: "group",
564
+ label: "Manual groups",
565
+ aliases: ["group", "manual-groups", "manual-group"],
566
+ defaultFields: ["id", "name", "description", "instanceId", "isRevert", "createdAt", "updatedAt"],
567
+ dangerousDelete: true
568
+ },
569
+ {
570
+ name: "org-units",
571
+ delegate: "orgUnit",
572
+ label: "Org units",
573
+ aliases: ["org-unit", "ou", "ous"],
574
+ defaultFields: ["id", "name", "code", "type", "googleOuId", "parentId", "instanceId", "instanceCountryParentId", "createdAt", "updatedAt"],
575
+ dangerousDelete: true
576
+ },
577
+ {
578
+ name: "user-org-units",
579
+ delegate: "userOrgUnit",
580
+ label: "User org unit assignments",
581
+ aliases: ["user-org-unit", "ou-memberships"],
582
+ defaultFields: ["userId", "orgUnitId", "primary", "assignedAt"],
583
+ instanceField: null,
584
+ dangerousDelete: true
585
+ },
586
+ {
587
+ name: "ou-admin-scopes",
588
+ delegate: "ouAdminOrgUnitScope",
589
+ label: "OU admin scopes",
590
+ aliases: ["ou-admin-scope"],
591
+ defaultFields: ["userId", "orgUnitId", "assignedAt"],
592
+ instanceField: null,
593
+ dangerousDelete: true
594
+ },
595
+ {
596
+ name: "entity-rule-configs",
597
+ delegate: "entityRuleConfig",
598
+ label: "Entity restriction rules",
599
+ aliases: ["entity-rules", "content-restriction-rules", "restrictions"],
600
+ defaultFields: ["id", "instanceId", "entityId", "restrictionMode", "categoryIds", "learningPathRestrictionMode", "learningPathIds", "alphaAllPrograms", "alphaProgramIds", "updatedAt"],
601
+ dangerousDelete: true
602
+ },
499
603
  {
500
604
  name: "users",
501
605
  delegate: "user",
@@ -509,7 +613,64 @@ var resources = [
509
613
  delegate: "accessPass",
510
614
  label: "Access passes",
511
615
  aliases: ["access-pass", "passes"],
512
- defaultFields: ["id", "userId", "instanceId", "createdAt", "updatedAt"]
616
+ defaultFields: ["id", "userId", "type", "startAt", "expireAt", "givenAt", "createdAt", "updatedAt"],
617
+ instanceField: "user.instanceID",
618
+ dangerousDelete: true
619
+ },
620
+ {
621
+ name: "analytics",
622
+ delegate: "analytics",
623
+ label: "Analytics events",
624
+ aliases: ["analytics-events"],
625
+ defaultFields: ["id", "instanceId", "userId", "pageId", "createdAt"]
626
+ },
627
+ {
628
+ name: "user-paths",
629
+ delegate: "userPath",
630
+ label: "User course completions",
631
+ aliases: ["user-path", "course-completions"],
632
+ defaultFields: ["id", "userId", "pageId", "isAchieved", "createdAt", "updatedAt"],
633
+ instanceField: null
634
+ },
635
+ {
636
+ name: "quiz-attempts",
637
+ delegate: "userQuizAttempt",
638
+ label: "Quiz attempts",
639
+ aliases: ["quiz-attempt", "attempts"],
640
+ defaultFields: ["id", "userId", "quizId", "pageId", "score", "percentage", "passed", "isCompleted", "createdAt", "updatedAt"],
641
+ instanceField: null
642
+ },
643
+ {
644
+ name: "chromebook-progress",
645
+ delegate: "chromebookUserProgress",
646
+ label: "Chromebook progress",
647
+ aliases: ["chromebook-user-progress"],
648
+ defaultFields: ["id", "userId", "exerciseId", "currentStep", "isCompleted", "startedAt", "completedAt", "createdAt", "updatedAt"],
649
+ instanceField: null
650
+ },
651
+ {
652
+ name: "user-badges",
653
+ delegate: "userBadge",
654
+ label: "User badges",
655
+ aliases: ["user-badge"],
656
+ defaultFields: ["id", "userId", "badgeId", "obtainedAt", "read"],
657
+ instanceField: null
658
+ },
659
+ {
660
+ name: "user-learning-paths",
661
+ delegate: "userLearningPath",
662
+ label: "User learning paths",
663
+ aliases: ["user-learning-path"],
664
+ defaultFields: ["id", "userId", "learningPathId", "isCompleted", "startedAt", "completedAt", "createdAt", "updatedAt"],
665
+ instanceField: null
666
+ },
667
+ {
668
+ name: "user-learning-path-item-completions",
669
+ delegate: "userLearningPathItemCompletion",
670
+ label: "User learning path item completions",
671
+ aliases: ["learning-path-item-completions", "user-learning-path-item-completion"],
672
+ defaultFields: ["id", "userId", "learningPathItemId", "completedAt"],
673
+ instanceField: null
513
674
  }
514
675
  ];
515
676
  var findResource = (name) => {
@@ -548,6 +709,19 @@ var runCommand = async (ctx) => {
548
709
  return runSyncCommand(actionOrResource, ctx);
549
710
  if (group === "cache")
550
711
  return runCacheCommand(actionOrResource, ctx);
712
+ if (group === "feedback")
713
+ return runFeedbackCommand(actionOrResource, maybeAction, ctx);
714
+ if (group === "access")
715
+ return runAccessCommand(actionOrResource, ctx);
716
+ if (group === "entities")
717
+ return runEntitiesCommand(actionOrResource, maybeAction, ctx);
718
+ if (group === "org-units-sync")
719
+ return runOrgUnitsSyncCommand(actionOrResource, ctx);
720
+ if (group === "ambassadors" && actionOrResource === "label")
721
+ return runAmbassadorsCommand(actionOrResource, ctx);
722
+ if ((group === "instances" || group === "instance") && (actionOrResource === "create" || actionOrResource === "create-plan")) {
723
+ return runInstanceCreationCommand(actionOrResource, ctx);
724
+ }
551
725
  const resource = findResource(group);
552
726
  return runResourceCommand(resource, actionOrResource, maybeAction, rest, ctx);
553
727
  };
@@ -612,7 +786,7 @@ var listResource = async (resource, ctx) => {
612
786
  const instanceId = getStringFlag(ctx, "instance") ?? defaultInstanceId(resource);
613
787
  const instanceField = resource.instanceField === undefined ? "instanceId" : resource.instanceField;
614
788
  if (instanceId && instanceField)
615
- where[instanceField] = instanceId;
789
+ setWhereValue(where, instanceField, instanceId);
616
790
  searchParams.set("where", JSON.stringify(where));
617
791
  searchParams.set("fields", getFields(resource, ctx).join(","));
618
792
  searchParams.set("take", String(getNumberFlag(ctx, "take") ?? 25));
@@ -637,7 +811,7 @@ var createResource = async (resource, ctx) => {
637
811
  const data = parseJsonObject(getStringFlag(ctx, "data"), "--data");
638
812
  const instanceId = getStringFlag(ctx, "instance") ?? defaultInstanceId(resource);
639
813
  const instanceField = resource.instanceField === undefined ? "instanceId" : resource.instanceField;
640
- if (instanceId && instanceField && data[instanceField] === undefined)
814
+ if (instanceId && instanceField && !instanceField.includes(".") && data[instanceField] === undefined)
641
815
  data[instanceField] = instanceId;
642
816
  if (Object.keys(data).length === 0)
643
817
  throw new CliError("Missing --data JSON", 2);
@@ -695,6 +869,232 @@ var deleteResource = async (resource, id, ctx) => {
695
869
  })
696
870
  });
697
871
  };
872
+ var runFeedbackCommand = async (action, feedbackId, ctx) => {
873
+ if (!action || action === "help")
874
+ return feedbackHelp();
875
+ if ((action === "claim" || action === "send-claim") && !feedbackId) {
876
+ throw new CliError("Missing feedback id", 2);
877
+ }
878
+ if (action === "claim") {
879
+ return requestApi("/api/cli/feedback/claim", {
880
+ method: "POST",
881
+ body: JSON.stringify({
882
+ feedbackId,
883
+ dryRun: hasFlag(ctx, "dry-run")
884
+ })
885
+ });
886
+ }
887
+ if (action === "send-claim") {
888
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
889
+ throw new CliError("Sending feedback email requires --yes or --dry-run", 2);
890
+ }
891
+ return requestApi("/api/cli/feedback/send-claim", {
892
+ method: "POST",
893
+ body: JSON.stringify({
894
+ feedbackId,
895
+ recipientEmail: getStringFlag(ctx, "recipient-email"),
896
+ recipientName: getStringFlag(ctx, "recipient-name"),
897
+ ccEmails: splitCsv(getStringFlag(ctx, "cc")),
898
+ subject: getStringFlag(ctx, "subject"),
899
+ body: getStringFlag(ctx, "body"),
900
+ dryRun: hasFlag(ctx, "dry-run")
901
+ })
902
+ });
903
+ }
904
+ if (action === "send-reply") {
905
+ if (!feedbackId)
906
+ throw new CliError("Missing feedback id", 2);
907
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
908
+ throw new CliError("Sending feedback reply email requires --yes or --dry-run", 2);
909
+ }
910
+ const subject = getStringFlag(ctx, "subject");
911
+ const body = getStringFlag(ctx, "body");
912
+ if (!subject || !body)
913
+ throw new CliError("Missing --subject or --body", 2);
914
+ return requestApi("/api/cli/feedback/send-reply", {
915
+ method: "POST",
916
+ body: JSON.stringify({
917
+ feedbackId,
918
+ subject,
919
+ body,
920
+ translatedSubject: getStringFlag(ctx, "translated-subject"),
921
+ translatedBody: getStringFlag(ctx, "translated-body"),
922
+ userLanguage: getStringFlag(ctx, "user-language"),
923
+ currentLanguage: getStringFlag(ctx, "current-language") ?? "fr",
924
+ dryRun: hasFlag(ctx, "dry-run")
925
+ })
926
+ });
927
+ }
928
+ throw new CliError(`Unknown feedback command "${action}"`, 2);
929
+ };
930
+ var runInstanceCreationCommand = async (action, ctx) => {
931
+ if (!action || action === "help" || action === "create-plan")
932
+ return instanceCreateHelp();
933
+ if (action !== "create")
934
+ throw new CliError(`Unknown instances command "${action}"`, 2);
935
+ const data = parseJsonObject(getStringFlag(ctx, "data"), "--data");
936
+ if (Object.keys(data).length === 0)
937
+ throw new CliError("Missing --data JSON", 2);
938
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
939
+ throw new CliError("Guided instance creation writes production data. Add --yes or use --dry-run.", 2);
940
+ }
941
+ return requestApi("/api/cli/instances/create", {
942
+ method: "POST",
943
+ body: JSON.stringify({
944
+ data,
945
+ dryRun: hasFlag(ctx, "dry-run")
946
+ })
947
+ });
948
+ };
949
+ var runAccessCommand = async (action, ctx) => {
950
+ if (!action || action === "help")
951
+ return accessHelp();
952
+ if (action === "grant") {
953
+ const userId = getStringFlag(ctx, "user");
954
+ if (!userId)
955
+ throw new CliError("Missing --user", 2);
956
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
957
+ throw new CliError("Granting access writes production data. Add --yes or use --dry-run.", 2);
958
+ }
959
+ return requestApi("/api/cli/access/grant", {
960
+ method: "POST",
961
+ body: JSON.stringify({
962
+ userId,
963
+ type: getStringFlag(ctx, "type") ?? "DEFAULT",
964
+ startAt: getStringFlag(ctx, "start-at"),
965
+ customDurationDays: getNumberFlag(ctx, "custom-duration-days"),
966
+ preferredLanguage: getStringFlag(ctx, "preferred-language"),
967
+ dryRun: hasFlag(ctx, "dry-run")
968
+ })
969
+ });
970
+ }
971
+ if (action === "revoke-active") {
972
+ const userId = getStringFlag(ctx, "user");
973
+ if (!userId)
974
+ throw new CliError("Missing --user", 2);
975
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
976
+ throw new CliError("Revoking access writes production data. Add --yes or use --dry-run.", 2);
977
+ }
978
+ return requestApi("/api/cli/access/revoke-active", {
979
+ method: "POST",
980
+ body: JSON.stringify({
981
+ userId,
982
+ dryRun: hasFlag(ctx, "dry-run")
983
+ })
984
+ });
985
+ }
986
+ throw new CliError(`Unknown access command "${action}"`, 2);
987
+ };
988
+ var runEntitiesCommand = async (action, entityId, ctx) => {
989
+ if (!action || action === "help")
990
+ return entitiesHelp();
991
+ const instanceId = getStringFlag(ctx, "instance");
992
+ if (["list", "detail", "access-summary", "sync-google-groups", "save-access-rules", "set-restrictions", "set-page-visibility"].includes(action) && !instanceId) {
993
+ throw new CliError("Missing --instance", 2);
994
+ }
995
+ if (action === "list") {
996
+ return requestApi(`/api/cli/entities/list?${entitySearchParams(ctx).toString()}`);
997
+ }
998
+ if (action === "detail") {
999
+ if (!entityId)
1000
+ throw new CliError("Missing entity id", 2);
1001
+ const searchParams = entitySearchParams(ctx);
1002
+ searchParams.set("entityId", entityId);
1003
+ return requestApi(`/api/cli/entities/detail?${searchParams.toString()}`);
1004
+ }
1005
+ if (action === "access-summary") {
1006
+ return requestApi(`/api/cli/entities/access-summary?${entitySearchParams(ctx).toString()}`);
1007
+ }
1008
+ if (action === "sync-google-groups") {
1009
+ return requestApi("/api/cli/entities/sync-google-groups", {
1010
+ method: "POST",
1011
+ body: JSON.stringify({
1012
+ instanceId,
1013
+ language: getStringFlag(ctx, "language") ?? "en",
1014
+ dryRun: hasFlag(ctx, "dry-run")
1015
+ })
1016
+ });
1017
+ }
1018
+ if (action === "save-access-rules") {
1019
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
1020
+ throw new CliError("Changing instance access rules writes production data. Add --yes or use --dry-run.", 2);
1021
+ }
1022
+ return requestApi("/api/cli/entities/save-access-rules", {
1023
+ method: "POST",
1024
+ body: JSON.stringify({
1025
+ instanceId,
1026
+ entityIds: splitCsv(getStringFlag(ctx, "entity-ids")),
1027
+ dryRun: hasFlag(ctx, "dry-run")
1028
+ })
1029
+ });
1030
+ }
1031
+ if (action === "set-restrictions") {
1032
+ const selectedEntityId = entityId ?? getStringFlag(ctx, "entity-id");
1033
+ if (!selectedEntityId)
1034
+ throw new CliError("Missing entity id", 2);
1035
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
1036
+ throw new CliError("Changing content restrictions writes production data. Add --yes or use --dry-run.", 2);
1037
+ }
1038
+ return requestApi("/api/cli/entities/set-restrictions", {
1039
+ method: "POST",
1040
+ body: JSON.stringify({
1041
+ instanceId,
1042
+ entityId: selectedEntityId,
1043
+ restrictionMode: getStringFlag(ctx, "restriction-mode"),
1044
+ categoryIds: splitCsv(getStringFlag(ctx, "category-ids")),
1045
+ learningPathRestrictionMode: getStringFlag(ctx, "learning-path-restriction-mode"),
1046
+ learningPathIds: splitCsv(getStringFlag(ctx, "learning-path-ids")),
1047
+ alphaAllPrograms: hasFlag(ctx, "alpha-all-programs"),
1048
+ alphaProgramIds: splitCsv(getStringFlag(ctx, "alpha-program-ids")),
1049
+ dryRun: hasFlag(ctx, "dry-run")
1050
+ })
1051
+ });
1052
+ }
1053
+ if (action === "set-page-visibility") {
1054
+ const pageId = getStringFlag(ctx, "page");
1055
+ if (!pageId)
1056
+ throw new CliError("Missing --page", 2);
1057
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
1058
+ throw new CliError("Changing page visibility writes production data. Add --yes or use --dry-run.", 2);
1059
+ }
1060
+ return requestApi("/api/cli/entities/set-page-visibility", {
1061
+ method: "POST",
1062
+ body: JSON.stringify({
1063
+ instanceId,
1064
+ pageId,
1065
+ entityIds: splitCsv(getStringFlag(ctx, "entity-ids")),
1066
+ dryRun: hasFlag(ctx, "dry-run")
1067
+ })
1068
+ });
1069
+ }
1070
+ throw new CliError(`Unknown entities command "${action}"`, 2);
1071
+ };
1072
+ var runOrgUnitsSyncCommand = async (action, ctx) => {
1073
+ if (!action || action === "help")
1074
+ return orgUnitsSyncHelp();
1075
+ if (action !== "google")
1076
+ throw new CliError(`Unknown org-units-sync command "${action}"`, 2);
1077
+ const instanceId = getStringFlag(ctx, "instance");
1078
+ if (!instanceId)
1079
+ throw new CliError("Missing --instance", 2);
1080
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
1081
+ throw new CliError("Google OU sync writes org-unit and membership data. Add --yes or use --dry-run.", 2);
1082
+ }
1083
+ return requestApi("/api/cli/org-units/sync-google", {
1084
+ method: "POST",
1085
+ body: JSON.stringify({
1086
+ instanceId,
1087
+ dryRun: hasFlag(ctx, "dry-run")
1088
+ })
1089
+ });
1090
+ };
1091
+ var runAmbassadorsCommand = async (_action, ctx) => {
1092
+ const instanceId = getStringFlag(ctx, "instance");
1093
+ if (!instanceId)
1094
+ throw new CliError("Missing --instance", 2);
1095
+ const language = getStringFlag(ctx, "language") ?? "fr";
1096
+ return requestApi(`/api/cli/ambassadors/label?instanceId=${encodeURIComponent(instanceId)}&language=${encodeURIComponent(language)}`);
1097
+ };
698
1098
  var runSyncCommand = async (action, ctx) => {
699
1099
  if (!action || action === "help")
700
1100
  return syncHelp();
@@ -889,7 +1289,31 @@ var getTargetInstanceIds = (ctx) => {
889
1289
  ]));
890
1290
  };
891
1291
  var getFields = (resource, ctx) => splitCsv(getStringFlag(ctx, "fields")).length > 0 ? splitCsv(getStringFlag(ctx, "fields")) : resource.defaultFields;
1292
+ var entitySearchParams = (ctx) => {
1293
+ const searchParams = new URLSearchParams;
1294
+ const instanceId = getStringFlag(ctx, "instance");
1295
+ const language = getStringFlag(ctx, "language") ?? "en";
1296
+ if (instanceId)
1297
+ searchParams.set("instanceId", instanceId);
1298
+ if (language)
1299
+ searchParams.set("language", language);
1300
+ return searchParams;
1301
+ };
892
1302
  var splitCsv = (value) => value ? value.split(",").map((item) => item.trim()).filter(Boolean) : [];
1303
+ var setWhereValue = (where, fieldPath, value) => {
1304
+ const parts = fieldPath.split(".").map((part) => part.trim()).filter(Boolean);
1305
+ if (parts.length === 0)
1306
+ return;
1307
+ let cursor = where;
1308
+ for (const part of parts.slice(0, -1)) {
1309
+ const existing = cursor[part];
1310
+ if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
1311
+ cursor[part] = {};
1312
+ }
1313
+ cursor = cursor[part];
1314
+ }
1315
+ cursor[parts[parts.length - 1]] = value;
1316
+ };
893
1317
  var GLOBAL_DEFAULT_RESOURCES = new Set([
894
1318
  "pages",
895
1319
  "topics",
@@ -979,6 +1403,22 @@ var schemaHelp = () => ({
979
1403
  { name: "sync presets", writes: false },
980
1404
  { name: "cache scopes", writes: false },
981
1405
  { name: "cache invalidate", required: ["--instance"], flags: ["--scope", "--languages", "--yes", "--dry-run"], writes: true },
1406
+ { name: "feedback claim", args: ["feedbackId"], flags: ["--dry-run"], writes: true },
1407
+ { name: "feedback send-claim", args: ["feedbackId"], flags: ["--recipient-email", "--recipient-name", "--cc", "--subject", "--body", "--yes", "--dry-run"], writes: true },
1408
+ { name: "feedback send-reply", args: ["feedbackId"], flags: ["--subject", "--body", "--translated-subject", "--translated-body", "--user-language", "--current-language", "--yes", "--dry-run"], writes: true },
1409
+ { name: "access grant", required: ["--user"], flags: ["--type", "--start-at", "--custom-duration-days", "--preferred-language", "--yes", "--dry-run"], writes: true },
1410
+ { name: "access revoke-active", required: ["--user"], flags: ["--yes", "--dry-run"], writes: true },
1411
+ { name: "instances create-plan", writes: false },
1412
+ { name: "instances create", flags: ["--data", "--yes", "--dry-run"], writes: true },
1413
+ { name: "entities list", required: ["--instance"], flags: ["--language"], writes: false },
1414
+ { name: "entities detail", args: ["entityId"], required: ["--instance"], flags: ["--language"], writes: false },
1415
+ { name: "entities access-summary", required: ["--instance"], writes: false },
1416
+ { name: "entities sync-google-groups", required: ["--instance"], flags: ["--dry-run"], writes: false },
1417
+ { name: "entities save-access-rules", required: ["--instance", "--entity-ids"], flags: ["--yes", "--dry-run"], writes: true },
1418
+ { name: "entities set-restrictions", args: ["entityId"], required: ["--instance"], flags: ["--category-ids", "--learning-path-ids", "--alpha-program-ids", "--alpha-all-programs", "--yes", "--dry-run"], writes: true },
1419
+ { name: "entities set-page-visibility", required: ["--instance", "--page"], flags: ["--entity-ids", "--yes", "--dry-run"], writes: true },
1420
+ { name: "org-units-sync google", required: ["--instance"], flags: ["--yes", "--dry-run"], writes: true },
1421
+ { name: "ambassadors label", required: ["--instance"], flags: ["--language"], writes: false },
982
1422
  ...resources.flatMap((resource) => [
983
1423
  { name: `${resource.name} list`, writes: false, flags: ["--where", "--fields", "--take", "--skip", "--order-by", "--instance", "--dry-run"] },
984
1424
  { name: `${resource.name} get`, args: ["id"], writes: false },
@@ -1037,6 +1477,71 @@ var cacheHelp = () => ({
1037
1477
  scopes: ["all", "pages", "pages-knowledge", "menu-bundle", "applications"],
1038
1478
  note: "Uses the same deploy-cache version bump system as the super-admin content settings screen."
1039
1479
  });
1480
+ var feedbackHelp = () => ({
1481
+ usage: [
1482
+ "gskills-admin feedback send-reply <feedbackId> --subject 'GSkills - ...' --body 'Bonjour...' --dry-run",
1483
+ "gskills-admin feedback send-reply <feedbackId> --subject 'GSkills - ...' --body 'Bonjour...' --yes",
1484
+ "gskills-admin feedback claim <feedbackId> --dry-run",
1485
+ "gskills-admin feedback claim <feedbackId>",
1486
+ "gskills-admin feedback send-claim <feedbackId> --recipient-email user@example.com --subject '...' --body '...' --yes"
1487
+ ],
1488
+ note: "send-reply is the normal feedback detail email template flow. claim/send-claim is only the SLA ticket-taken-in-charge flow."
1489
+ });
1490
+ var instanceCreateHelp = () => ({
1491
+ usage: [
1492
+ "gskills-admin instances create-plan --output json",
1493
+ `gskills-admin instances create --data '{"name":"Client","URL":"client","licenceType":"STARTER","tokensAllowed":50}' --dry-run --output json`,
1494
+ "gskills-admin instances create --data '{...}' --yes --output json"
1495
+ ],
1496
+ path: [
1497
+ "1. Créer l'instance: name, URL, clientType, RunningState",
1498
+ "2. Licence et sièges: licenceType, tokensAllowed",
1499
+ "3. Langues: languageCodes, mainLanguage",
1500
+ "4. Fonctionnalités: aiEnabled",
1501
+ "5. Accès: InstanceAddStyle with domainGranular, accountGranular or later entity rules",
1502
+ "6. Contacts client: clientContacts, each becomes COMMANDITARY with unlimited pass",
1503
+ "7. Synchroniser: launchChecklist.syncFromGlobal",
1504
+ "8. Valider: one final production write",
1505
+ "9. Préparer la livraison: use the generated delivery email outside the CLI"
1506
+ ],
1507
+ requiredData: ["name", "URL", "licenceType", "tokensAllowed"],
1508
+ defaults: {
1509
+ RunningState: true,
1510
+ aiEnabled: true,
1511
+ languageCodes: ["fr", "en"],
1512
+ mainLanguage: "fr",
1513
+ InstanceAddStyle: "ALL unless granular values are provided",
1514
+ clientType: "NUMERICOACH_LICENSE",
1515
+ syncFromGlobal: true
1516
+ },
1517
+ warning: "This uses the guided creation workflow. Raw Prisma instance creation is intentionally not the default CLI path."
1518
+ });
1519
+ var accessHelp = () => ({
1520
+ usage: [
1521
+ "gskills-admin access grant --user <userId> --type DEFAULT --dry-run",
1522
+ "gskills-admin access grant --user <userId> --type PASS_90_DAYS --preferred-language fr --yes",
1523
+ "gskills-admin access revoke-active --user <userId> --yes"
1524
+ ],
1525
+ types: ["DEFAULT", "PASS_90_DAYS", "PASS_12_MONTHS", "CUSTOM", "UNLIMITED"]
1526
+ });
1527
+ var entitiesHelp = () => ({
1528
+ usage: [
1529
+ "gskills-admin entities list --instance <instanceId>",
1530
+ "gskills-admin entities detail <entityId> --instance <instanceId>",
1531
+ "gskills-admin entities access-summary --instance <instanceId>",
1532
+ "gskills-admin entities save-access-rules --instance <instanceId> --entity-ids manual-group:<id>,org-unit:<id> --dry-run",
1533
+ "gskills-admin entities set-restrictions <entityId> --instance <instanceId> --category-ids <id,id> --learning-path-ids <id,id> --yes",
1534
+ "gskills-admin entities set-page-visibility --instance <instanceId> --page <pageId> --entity-ids google-group:team@example.com --yes"
1535
+ ],
1536
+ note: "Entity ids use the shared admin entity format: manual-group:<id>, org-unit:<id>, google-group:<email>."
1537
+ });
1538
+ var orgUnitsSyncHelp = () => ({
1539
+ usage: [
1540
+ "gskills-admin org-units-sync google --instance <instanceId> --dry-run",
1541
+ "gskills-admin org-units-sync google --instance <instanceId> --yes"
1542
+ ],
1543
+ note: "Uses the same Google Admin OU sync engine as the instance admin UI."
1544
+ });
1040
1545
  var resourceHelp = (resource) => ({
1041
1546
  resource: resource.name,
1042
1547
  label: resource.label,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@numericoach/gskills-admin-cli",
3
- "version": "0.1.2",
3
+ "version": "0.1.4",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Admin-only CLI for GSkills super-admin operations.",
@@ -258,6 +258,154 @@ gskills-admin cache invalidate --instance <instanceId> --scope menu-bundle --yes
258
258
  gskills-admin cache invalidate --instance <instanceId> --scope all --yes --output json
259
259
  ```
260
260
 
261
+ ## Feedback Emails
262
+
263
+ Use `send-reply` for the normal email available from the feedback detail dialog. It uses the `GSkillsEmail` template, sends to the feedback user, stores a `FeedbackReply`, updates `repliedAt`, and writes admin logs.
264
+
265
+ ```bash
266
+ gskills-admin feedback send-reply <feedbackId> --subject "GSkills - ..." --body "Bonjour..." --dry-run --output json
267
+ gskills-admin feedback send-reply <feedbackId> --subject "GSkills - ..." --body "Bonjour..." --yes --output json
268
+ ```
269
+
270
+ If the user language differs from French, pass the edited translated fields generated or reviewed by the agent:
271
+
272
+ ```bash
273
+ gskills-admin feedback send-reply <feedbackId> --subject "GSkills - ..." --body "Bonjour..." --translated-subject "GSkills - ..." --translated-body "Hello..." --user-language en --current-language fr --dry-run --output json
274
+ ```
275
+
276
+ The claim commands below are not the normal feedback reply system. They are only for the SLA "ticket pris en charge" flow.
277
+
278
+ ```bash
279
+ gskills-admin feedback claim <feedbackId> --dry-run --output json
280
+ gskills-admin feedback claim <feedbackId> --output json
281
+ gskills-admin feedback send-claim <feedbackId> --recipient-email user@example.com --subject "GSkills - Ticket pris en charge" --body "Bonjour..." --dry-run --output json
282
+ gskills-admin feedback send-claim <feedbackId> --recipient-email user@example.com --subject "GSkills - Ticket pris en charge" --body "Bonjour..." --yes --output json
283
+ ```
284
+
285
+ Rules:
286
+
287
+ - For normal feedback responses, use `send-reply`.
288
+ - Dry-run claim first to inspect recipient, CC recipients and draft.
289
+ - Send only after the ticket is claimed by the same CLI user.
290
+ - CC recipients must be allowed by instance SLA flags.
291
+ - All feedback email sends are admin-logged with CLI metadata.
292
+
293
+ ## Guided Instance Creation
294
+
295
+ Never use raw `instances create` as a blind Prisma row insert. The CLI `instances create` command is wired to the same guided creation path as `/fr/super-admin/instances/create`.
296
+
297
+ ```bash
298
+ gskills-admin instances create-plan --output json
299
+ gskills-admin instances create --data '{"name":"Client","URL":"client","licenceType":"STARTER","tokensAllowed":50}' --dry-run --output json
300
+ gskills-admin instances create --data '{"name":"Client","URL":"client","licenceType":"STARTER","tokensAllowed":50}' --yes --output json
301
+ ```
302
+
303
+ The guided path expects:
304
+
305
+ - identity: `name`, `URL`, `projectData.clientType`, `RunningState`
306
+ - licence: `licenceType`, `tokensAllowed`
307
+ - languages: `languageCodes`, `mainLanguage`
308
+ - features: `aiEnabled`
309
+ - access: `InstanceAddStyle`, plus `domainGranular`, `accountGranular`, or `groupGranular`
310
+ - contacts: `clientContacts`, each created or attached as `COMMANDITARY` with an unlimited pass
311
+ - launch: `launchChecklist.syncFromGlobal`
312
+
313
+ Default values match the UI where possible: active instance, IA enabled, `fr,en`, main language `fr`, client type `NUMERICOACH_LICENSE`, global sync enabled.
314
+
315
+ Use dry-run to inspect the full plan and warnings. The real run creates the instance, connects languages, creates the `quiz-retake` flag, project data, client commanditary accounts, unlimited access passes, optional global sync, deploy-cache invalidation, and admin log.
316
+
317
+ ## Accesses
318
+
319
+ Use `access grant` and `access revoke-active` instead of raw `access-passes` writes when the operation should trigger workflows and admin logs.
320
+
321
+ ```bash
322
+ gskills-admin access grant --user <userId> --type DEFAULT --dry-run --output json
323
+ gskills-admin access grant --user <userId> --type PASS_90_DAYS --preferred-language fr --yes --output json
324
+ gskills-admin access revoke-active --user <userId> --dry-run --output json
325
+ gskills-admin access revoke-active --user <userId> --yes --output json
326
+ ```
327
+
328
+ Types are `DEFAULT`, `PASS_90_DAYS`, `PASS_12_MONTHS`, `CUSTOM`, and `UNLIMITED`.
329
+
330
+ ## Entities And Restrictions
331
+
332
+ Entities are the shared segmentation layer for manual groups, Google groups, and Google Admin OUs.
333
+
334
+ ```bash
335
+ gskills-admin entities list --instance <instanceId> --language fr --output json
336
+ gskills-admin entities detail manual-group:<groupId> --instance <instanceId> --language fr --output json
337
+ gskills-admin entities access-summary --instance <instanceId> --output json
338
+ gskills-admin entities sync-google-groups --instance <instanceId> --output json
339
+ gskills-admin org-units-sync google --instance <instanceId> --dry-run --output json
340
+ gskills-admin org-units-sync google --instance <instanceId> --yes --output json
341
+ ```
342
+
343
+ Entity ids use:
344
+
345
+ - `manual-group:<groupId>`
346
+ - `org-unit:<orgUnitId>`
347
+ - `google-group:<email>`
348
+
349
+ For instance access rules:
350
+
351
+ ```bash
352
+ gskills-admin entities save-access-rules --instance <instanceId> --entity-ids manual-group:<id>,org-unit:<id> --dry-run --output json
353
+ gskills-admin entities save-access-rules --instance <instanceId> --entity-ids manual-group:<id>,org-unit:<id> --yes --output json
354
+ ```
355
+
356
+ For content restrictions:
357
+
358
+ ```bash
359
+ gskills-admin entities set-restrictions manual-group:<id> --instance <instanceId> --category-ids <categoryId,categoryId> --learning-path-ids <pathId,pathId> --dry-run --output json
360
+ gskills-admin entities set-restrictions manual-group:<id> --instance <instanceId> --category-ids <categoryId,categoryId> --learning-path-ids <pathId,pathId> --yes --output json
361
+ gskills-admin entities set-page-visibility --instance <instanceId> --page <pageId> --entity-ids google-group:team@example.com --dry-run --output json
362
+ gskills-admin entities set-page-visibility --instance <instanceId> --page <pageId> --entity-ids google-group:team@example.com --yes --output json
363
+ ```
364
+
365
+ These commands update the same underlying shared restriction models as the UI and invalidate the dependent deploy cache scope.
366
+
367
+ ## Ambassadors
368
+
369
+ Ambassadors can be shown as ambassadors, experts or champions depending on the instance flag.
370
+
371
+ ```bash
372
+ gskills-admin ambassadors label --instance <instanceId> --language fr --output json
373
+ gskills-admin ambassadors list --where '{"user":{"instanceID":"<instanceId>"}}' --output json
374
+ ```
375
+
376
+ Use the label command before writing user-facing copy.
377
+
378
+ ## Project Data And Analytics
379
+
380
+ Project data resources:
381
+
382
+ - `project-data`
383
+ - `project-contacts`
384
+ - `ticket-sla-rules`
385
+ - `ticket-sla-contacts`
386
+
387
+ Analytics-readable resources:
388
+
389
+ - `analytics`
390
+ - `user-paths`
391
+ - `quiz-attempts`
392
+ - `chromebook-progress`
393
+ - `user-badges`
394
+ - `user-learning-paths`
395
+ - `user-learning-path-item-completions`
396
+
397
+ Examples:
398
+
399
+ ```bash
400
+ gskills-admin project-data list --instance <instanceId> --output json
401
+ gskills-admin analytics list --where '{"instanceId":"<instanceId>"}' --take 100 --output json
402
+ gskills-admin quiz-attempts list --where '{"user":{"instanceID":"<instanceId>"}}' --take 100 --output json
403
+ ```
404
+
405
+ Prefer these read paths for analytics investigation. They are intentionally raw enough to match UI analytics data without giving the agent a DB URL.
406
+
407
+ ## Cache Scope Choice
408
+
261
409
  Prefer the narrowest scope:
262
410
 
263
411
  - `pages`
@@ -0,0 +1,164 @@
1
+ ---
2
+ name: gskills-instance-creation
3
+ description: Use when an agent must create a GSkills client instance or explain the guided super-admin instance creation flow.
4
+ ---
5
+
6
+ # Creation d'instance GSkills
7
+
8
+ Cette skill sert quand un agent doit creer une instance GSkills sans passer par l'UI.
9
+
10
+ Le principe est simple: la CLI doit suivre le chemin du formulaire `/fr/super-admin/instances/create`, pas creer une ligne `Instance` brute.
11
+
12
+ ## Comment l'UI fonctionne aujourd'hui
13
+
14
+ Le formulaire est un wizard en 9 etapes.
15
+
16
+ 1. Creer l'instance
17
+
18
+ - `name`: nom visible dans l'admin.
19
+ - `URL`: slug unique, utilise pour `https://<slug>.g-skills.fr/`.
20
+ - `projectData.clientType`: type commercial du client.
21
+ - `RunningState`: instance active ou fermee des la creation.
22
+
23
+ 2. Licence et sieges
24
+
25
+ - `licenceType`: `STARTER`, `PREMIUM`, ou `PRESTIGE`.
26
+ - `tokensAllowed`: nombre d'utilisateurs autorises.
27
+
28
+ 3. Langues
29
+
30
+ - `languageCodes`: langues actives.
31
+ - `mainLanguage`: langue principale.
32
+ - La langue principale doit etre dans les langues actives.
33
+ - Par defaut l'UI propose `fr` et `en`, avec `fr` en principal.
34
+
35
+ 4. Fonctionnalites
36
+
37
+ - `aiEnabled`: active ou desactive les fonctionnalites IA.
38
+ - Par defaut, l'IA est active.
39
+
40
+ 5. Acces a l'instance
41
+
42
+ Meme logique que Parametres > Acces.
43
+
44
+ - `ALL`: ouvert aux comptes autorises.
45
+ - `GRANULAR_DOMAIN`: necessite `domainGranular`.
46
+ - `GRANULAR_ACCOUNT`: necessite `accountGranular`.
47
+ - `GRANULAR_GOOGLE_GROUP`: les entites Google se terminent apres creation.
48
+ - `NONE`: aucun acces automatique, pass manuel uniquement.
49
+
50
+ 6. Contacts client
51
+
52
+ - `clientContacts`: emails, prenoms, noms, postes.
53
+ - Chaque contact devient `COMMANDITARY` sur l'instance.
54
+ - Chaque contact recoit un pass `UNLIMITED`.
55
+ - Le premier contact remplit les champs principaux de `InstanceProjectData`.
56
+ - Les suivants deviennent des `InstanceClientContact`.
57
+
58
+ 7. Synchroniser
59
+
60
+ - `launchChecklist.syncFromGlobal`.
61
+ - Si actif, le contenu global compatible avec les langues est copie.
62
+ - La synchro peut creer pages, categories, menus, quiz, parcours, connaissances, ressources, badges, exercices Chromebook et workflows.
63
+ - Le cache deploy est invalide apres la synchro.
64
+
65
+ 8. Valider
66
+
67
+ - Une seule action finale cree tout.
68
+ - L'UI loggue la creation avec un snapshot de l'instance et des contacts.
69
+
70
+ 9. Preparer la livraison
71
+
72
+ - L'UI prepare un email a copier dans Gmail.
73
+ - Cet email contient les liens d'acces, formulaire, notifications et prochaines etapes client.
74
+ - La CLI ne doit pas envoyer cet email automatiquement.
75
+
76
+ ## Comment le faire en CLI
77
+
78
+ Toujours commencer par le plan.
79
+
80
+ ```bash
81
+ gskills-admin instances create-plan --output json
82
+ ```
83
+
84
+ Ensuite preparer un payload JSON.
85
+
86
+ Payload minimal:
87
+
88
+ ```json
89
+ {
90
+ "name": "Client Exemple",
91
+ "URL": "client-exemple",
92
+ "licenceType": "STARTER",
93
+ "tokensAllowed": 50
94
+ }
95
+ ```
96
+
97
+ Payload complet courant:
98
+
99
+ ```json
100
+ {
101
+ "name": "Client Exemple",
102
+ "URL": "client-exemple",
103
+ "licenceType": "STARTER",
104
+ "tokensAllowed": 50,
105
+ "RunningState": true,
106
+ "aiEnabled": true,
107
+ "languageCodes": ["fr", "en"],
108
+ "mainLanguage": "fr",
109
+ "InstanceAddStyle": "GRANULAR_DOMAIN",
110
+ "domainGranular": ["client.com"],
111
+ "clientContacts": [
112
+ {
113
+ "email": "admin@client.com",
114
+ "firstName": "Marie",
115
+ "lastName": "Dupont",
116
+ "jobTitle": "Responsable formation"
117
+ }
118
+ ],
119
+ "projectData": {
120
+ "clientType": "NUMERICOACH_LICENSE"
121
+ },
122
+ "launchChecklist": {
123
+ "syncFromGlobal": true,
124
+ "prepareDeliveryEmail": true,
125
+ "requestWhitelist": true,
126
+ "requestOnboardingForm": true,
127
+ "requestUserImport": true,
128
+ "notes": ""
129
+ }
130
+ }
131
+ ```
132
+
133
+ Faire un dry-run.
134
+
135
+ ```bash
136
+ gskills-admin instances create --data '{"name":"Client Exemple","URL":"client-exemple","licenceType":"STARTER","tokensAllowed":50}' --dry-run --output json
137
+ ```
138
+
139
+ Verifier:
140
+
141
+ - slug disponible.
142
+ - langues attendues.
143
+ - mode d'acces coherent.
144
+ - contacts client corrects.
145
+ - synchro globale voulue ou non.
146
+ - warnings vides ou compris.
147
+
148
+ Puis creer.
149
+
150
+ ```bash
151
+ gskills-admin instances create --data '{"name":"Client Exemple","URL":"client-exemple","licenceType":"STARTER","tokensAllowed":50}' --yes --output json
152
+ ```
153
+
154
+ ## Regles agents
155
+
156
+ - Ne jamais utiliser un CRUD brut Prisma pour creer une instance.
157
+ - Ne jamais supposer le mode d'acces si le client a fourni domaines, emails ou groupes.
158
+ - Si `InstanceAddStyle = GRANULAR_DOMAIN`, il faut au moins un domaine.
159
+ - Si `InstanceAddStyle = GRANULAR_ACCOUNT`, il faut au moins un email.
160
+ - Pour `GRANULAR_GOOGLE_GROUP`, creer l'instance puis configurer les entites avec la CLI `entities`.
161
+ - Toujours faire `--dry-run` avant `--yes`.
162
+ - Apres creation, aller verifier les parametres et preparer l'email de livraison.
163
+ - Si la synchro initiale remonte un warning, ne pas l'ignorer. Lire les logs de sync avant de dire que tout est pret.
164
+