@looply/sdk 0.0.0-stage → 0.1.0

package/dist/errors.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * WHAT WENT WRONG, IN A FORM A PROGRAM CAN BRANCH ON.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 NO CLIENT MAY EVER PARSE AN ENGLISH MESSAGE.
+ *
+ * The server's wire shape is `{ statusCode, message }`, and the messages are
+ * good ones — controllers put real work into them, and a person reading a
+ * refusal should get a sentence rather than a symbol. But a message is written
+ * for a person and is changed for a person, so a client that branches on its
+ * text breaks the next time somebody improves the wording. That is the whole
+ * reason for this file.
+ *
+ * ⚠️ THE CODES ARE DERIVED FROM STATUS, NOT INVENTED ALONGSIDE IT. There are
+ * roughly 250 throw sites in the server and none of them carries a code today.
+ * Adding one to each would be a large, mechanical, error-prone edit whose only
+ * consumer is this file — so instead the mapping lives here, where it can be
+ * read in one screen, and a `code` the server DOES supply is preferred over the
+ * derived one. That is a narrower promise than "every refusal has a bespoke
+ * code", and it is the one that is true.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LooplyError = void 0;
+exports.isRetryable = isRetryable;
+exports.codeForStatus = codeForStatus;
+/**
+ * Whether trying the SAME request again could plausibly succeed.
+ *
+ * ⚠️ `timeout` IS RETRYABLE AND ALSO THE MOST DANGEROUS TO RETRY, which is why
+ * every mutating call in this SDK takes an idempotency key. A timed-out request
+ * may have been executed; retrying without a key is how one Start becomes two.
+ */
+function isRetryable(code) {
+    return code === 'unavailable' || code === 'timeout';
+}
+const BY_STATUS = {
+    400: 'invalid_request',
+    401: 'unauthorized',
+    403: 'forbidden',
+    404: 'not_found',
+    409: 'conflict',
+    410: 'gone',
+    422: 'invalid_request',
+};
+/**
+ * The code for an HTTP status.
+ *
+ * Anything unmapped is `unavailable`: an unrecognised 5xx is Looply failing, and
+ * an unrecognised 4xx is a refusal this client does not model — which the caller
+ * should treat as "not now" rather than as a specific promise.
+ */
+function codeForStatus(status) {
+    // 🔴 AN UNMAPPED 4xx IS `unavailable`, NOT `invalid_request`, AND THE
+    // DIFFERENCE IS A CLAIM THIS CLIENT CANNOT SUPPORT.
+    //
+    // `invalid_request` says, in its own words, "the request itself was wrong;
+    // retrying it unchanged will fail identically". For a status this SDK does not
+    // model — a 429 the day a rate limit is added, a 423, a 425 — that is simply
+    // false: the request was fine and the answer was "not now". `unavailable` is
+    // the weaker and honest claim, which is what the sentence above this function
+    // has always said it does.
+    //
+    // ⚠️ THE CODE USED TO DO THE OPPOSITE OF ITS OWN DOCUMENTATION. Nothing
+    // detected it because nothing tested this function at all, and the branch was
+    // UNREACHABLE at the time: the server emitted exactly 400, 401, 403, 404, 409
+    // and 503, every one of them mapped. So it was written as hardening for the
+    // next status somebody added server-side.
+    //
+    // 🔴 THAT NEXT STATUS ARRIVED, AND THE HARDENING WAS NOT ENOUGH. The membership
+    // route answers 410 for an activation code that expired or was withdrawn, and
+    // an unmapped 410 fell to `unavailable` — retryable — which tells a caller to
+    // keep presenting a code that will never work again. The census in
+    // `errors.spec.ts` is what caught it; 410 is mapped to `gone` above, and the
+    // default below is still the honest answer for a status nobody has modelled.
+    return BY_STATUS[status] ?? 'unavailable';
+}
+/**
+ * The one error type this SDK throws.
+ *
+ * 🔴 EVERY FAILURE PATH PRODUCES ONE OF THESE, including a network failure and a
+ * timeout — which are not HTTP statuses at all. A caller that has to distinguish
+ * "the server said no" from "there was no server" by catching two different
+ * shapes will eventually catch only one of them.
+ */
+class LooplyError extends Error {
+    status;
+    code;
+    currentVersion;
+    body;
+    constructor(init) {
+        super(init.message);
+        this.name = 'LooplyError';
+        this.status = init.status;
+        this.code = normalise(init.serverCode) ?? codeForStatus(init.status);
+        this.currentVersion = init.currentVersion;
+        this.body = init.body;
+    }
+    /** Whether trying this exact request again could plausibly succeed. */
+    get retryable() {
+        return isRetryable(this.code);
+    }
+}
+exports.LooplyError = LooplyError;
+/** A server-supplied code, but only if it is one this SDK actually models. */
+function normalise(code) {
+    const known = [
+        'unauthorized',
+        'forbidden',
+        'not_found',
+        'gone',
+        'conflict',
+        'invalid_request',
+        'unavailable',
+        'timeout',
+    ];
+    return known.find((k) => k === code);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAqDH,kCAEC;AAmBD,sCAwBC;AApDD;;;;;;GAMG;AACH,SAAgB,WAAW,CAAC,IAAqB;IAC/C,OAAO,IAAI,KAAK,aAAa,IAAI,IAAI,KAAK,SAAS,CAAC;AACtD,CAAC;AAED,MAAM,SAAS,GAA8C;IAC3D,GAAG,EAAE,iBAAiB;IACtB,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,UAAU;IACf,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,iBAAiB;CACvB,CAAC;AAEF;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,MAAc;IAC1C,sEAAsE;IACtE,oDAAoD;IACpD,EAAE;IACF,2EAA2E;IAC3E,+EAA+E;IAC/E,6EAA6E;IAC7E,6EAA6E;IAC7E,8EAA8E;IAC9E,2BAA2B;IAC3B,EAAE;IACF,wEAAwE;IACxE,8EAA8E;IAC9E,8EAA8E;IAC9E,4EAA4E;IAC5E,0CAA0C;IAC1C,EAAE;IACF,gFAAgF;IAChF,8EAA8E;IAC9E,8EAA8E;IAC9E,mEAAmE;IACnE,6EAA6E;IAC7E,6EAA6E;IAC7E,OAAO,SAAS,CAAC,MAAM,CAAC,IAAI,aAAa,CAAC;AAC5C,CAAC;AAYD;;;;;;;GAOG;AACH,MAAa,WAAY,SAAQ,KAAK;IAC3B,MAAM,CAAS;IACf,IAAI,CAAkB;IACtB,cAAc,CAAqB;IACnC,IAAI,CAAU;IAEvB,YAAY,IAAqB;QAC/B,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrE,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;IAED,uEAAuE;IACvE,IAAI,SAAS;QACX,OAAO,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;CACF;AAnBD,kCAmBC;AAED,8EAA8E;AAC9E,SAAS,SAAS,CAAC,IAAwB;IACzC,MAAM,KAAK,GAA+B;QACxC,cAAc;QACd,WAAW;QACX,WAAW;QACX,MAAM;QACN,UAAU;QACV,iBAAiB;QACjB,aAAa;QACb,SAAS;KACV,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;AACvC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @looply/sdk — the stable client contract.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 WHAT IS EXPORTED IS WHAT IS PROMISED.
+ *
+ * There is no `export *` here, and that is deliberate. A star export makes every
+ * future addition to any of these files public the moment somebody writes it,
+ * which is how an internal helper becomes a compatibility obligation nobody
+ * chose. Adding a name to this file is the act of promising it.
+ *
+ * ⚠️ NOTHING FROM `@looply/core` IS RE-EXPORTED. Core is the internal shared
+ * vocabulary of the server, the CLI and the app; it changes when they need it
+ * to. An external client that imported a core type through here would be pinned
+ * to an internal release cycle it cannot see.
+ */
+export { LooplyClient } from './client';
+export type { LooplyClientOptions } from './client';
+export { LooplyError, isRetryable, codeForStatus } from './errors';
+export type { LooplyErrorCode, LooplyErrorInit } from './errors';
+export type { ApprovalStateView, ApprovalView, CommandStatusView, EvidenceRefView, ExecutionStateView, GoalStateView, GoalView, GovernedExecutionView, ItemStateView, ItemView, KeeperAnswerView, KeeperCitationView, PageView, PlatformEventView, ProjectView, RunStatusView, GoalAutonomyReport, GoalAutonomyStateView, GoalAutonomyView, GoalEvidenceView, PresenceView, GoalVersionEvidenceView, EvidenceRunView, EvidenceRoundView, EvidenceGateStepView, EvidencePursuitView, EvidencePushView, DispositionKindView, CoverageKindView, EvidenceAnchorView, GoalRefView, RequirementCoverageView, RequirementLinkView, SourceCoverageView, RepositoryAnchorView, SourceAttestationView, SourceClassificationView, SourceDetailView, SourceDispositionView, SourceKindView, SourceRecordView, SourceStatementKindView, SourceStatementView, SourceView, StatementClassView, } from './views';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACnE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEjE,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,QAAQ,EACR,qBAAqB,EACrB,aAAa,EACb,QAAQ,EACR,gBAAgB,EAChB,kBAAkB,EAClB,QAAQ,EACR,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACvB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,UAAU,EACV,kBAAkB,GACnB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * @looply/sdk — the stable client contract.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 WHAT IS EXPORTED IS WHAT IS PROMISED.
+ *
+ * There is no `export *` here, and that is deliberate. A star export makes every
+ * future addition to any of these files public the moment somebody writes it,
+ * which is how an internal helper becomes a compatibility obligation nobody
+ * chose. Adding a name to this file is the act of promising it.
+ *
+ * ⚠️ NOTHING FROM `@looply/core` IS RE-EXPORTED. Core is the internal shared
+ * vocabulary of the server, the CLI and the app; it changes when they need it
+ * to. An external client that imported a core type through here would be pinned
+ * to an internal release cycle it cannot see.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codeForStatus = exports.isRetryable = exports.LooplyError = exports.LooplyClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "LooplyClient", { enumerable: true, get: function () { return client_1.LooplyClient; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "LooplyError", { enumerable: true, get: function () { return errors_1.LooplyError; } });
+Object.defineProperty(exports, "isRetryable", { enumerable: true, get: function () { return errors_1.isRetryable; } });
+Object.defineProperty(exports, "codeForStatus", { enumerable: true, get: function () { return errors_1.codeForStatus; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAEH,mCAAwC;AAA/B,sGAAA,YAAY,OAAA;AAGrB,mCAAmE;AAA1D,qGAAA,WAAW,OAAA;AAAE,qGAAA,WAAW,OAAA;AAAE,uGAAA,aAAa,OAAA"}