openpond-sdk 0.1.4 → 0.1.6

package/LEARNING.md

@@ -43,8 +43,53 @@ All client requests support an optional `AbortSignal`. Aborting a request does
 not cancel remote compute; use `cancel_grade` and read the authoritative terminal
 job state. Page through list responses with `nextCursor` as `afterId`.
 
+## Connect an application
+
+In the task format, open **Connect an application** and create a source credential.
+Copy it into the application's secret store before closing the panel. Credentials
+expire within 90 days and can be revoked from the same panel. The list contains
+metadata and key prefixes only; hosts store secret hashes.
+
+Use that credential as `OPENPOND_API_KEY` in the examples above. It authorizes
+`submitExample`, `submitFeedback` and `sourceConfiguration(sourceId)` for exactly
+one source and scope. Configuration returns the source and task-definition
+references, allowed splits and enabled status. It does not expose private
+evidence. Reading resources, grading, review, publication, training and credential
+management require the owning user's authenticated client.
+
+Owners can also manage credentials through the SDK:
+
+```ts
+import { createSourceCredentialRequest } from "openpond-sdk/learning";
+
+const request = createSourceCredentialRequest({
+  sourceId,
+  name: "Application intake",
+  expiresAt: new Date(Date.now() + 30 * 86_400_000).toISOString(),
+});
+const issued = await ownerClient.createSourceCredential(request);
+// Store issued.apiKey securely. Never log it or commit the prepared request.
+const page = await ownerClient.listSourceCredentials(sourceId, { limit: 30 });
+await ownerClient.revokeSourceCredential(sourceId, issued.credential.id);
+```
+
+Keep the prepared request in memory for a transport retry: the same operation ID
+and content returns the same credential, while changed content conflicts.
+Revocation is idempotent; repeating creation does not reactivate a revoked key.
+Use a new prepared request for a new credential. Disabling a source also prevents
+new evidence submission. Hosts enforce authentication, expiry and source scope
+on every request.
+
 ## Publish a reviewed batch to a hosted model
 
 Call `learning.publishBatch({ batchId, modelProjectId })` against the hosted API after sealing an approved batch. This stores its immutable Taskset package and attaches the exact release to the model. It does not start training. The service authorizes the model and batch in the same team and deduplicates publication by release identity.
 
 Model configuration can save `trainingSetup.rewardBindingRef` before selecting a Taskset. The reference pins a binding ID, revision and content hash; task compatibility and training readiness remain separate checks. Use `createModelProjectSaveRequest` with `createModelProjectsClient().checkConfiguration()` / `.saveConfiguration()` for hosted configuration operations, and `configurationCandidates()` for available starting models. Keep one request identity for transport retries.
+
+## Durable authoring drafts
+
+Reward, combined Reward and task-format editors save incomplete work separately from published releases. Use `AuthoringDraftInputSchema` with the corresponding typed fields schema. Drafts preserve incomplete JSON and JavaScript as strings; publishing still validates the finished resource. Drafts belong to the workspace and are not available to source credentials.
+
+Send `save_draft` with a stable `operationId`, the draft input and its `expectedRevision` (zero for a new draft). Retry the identical command after an uncertain response. Distinct edits against the same revision conflict rather than overwriting each other. List with `client.list("draft", { parentId: "reward", status: "draft", limit: 20 })`; the other target kinds are `definition` and `binding`.
+
+A draft's target and exact base release remain fixed. To publish, include `finalizeDraft: { draft: learningRef(savedDraft), targetKind: savedDraft.targetKind, release: learningRef(publishedRelease) }` in the `publish` or `publish_resources` command. The release and the draft's published status commit in one transaction; stale draft finalization rolls back publication. Archive unfinished work with `archive_draft` and its exact draft reference. Archived and published drafts cannot accept further edits.