API 24 and tasks docs

[crandmck]

Changes in this pull request

Clarify and document new API and add manifest tasks.

Developers should review the languages that they work on. Do we need further reviewers?

For information on where all the files are, see Notes at the bottom of this description.

Rust

@gpeacock and @andrewhalle to review

• Setup: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/setup/?lang=rust
• Reading manifest data: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/read?lang=rust
• Getting resources from a manifest: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/get-resources?lang=rust
• Attaching and signing a manifest: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/build?lang=rust

C++

@gpeacock to review

• Setup: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/setup/?lang=cpp
• Reading manifest data: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/read?lang=cpp
• Getting resources from a manifest: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/get-resources?lang=cpp
• Attaching and signing a manifest: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/build?lang=cpp

Python

@tmathern to review

• Setup: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/setup/?lang=python
• Reading manifest data: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/read?lang=python
• Getting resources from a manifest: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/get-resources?lang=python
• Attaching and signing a manifest: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/build?lang=python

JavaScript

@emensch to review

• Setup: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/setup/?lang=js
• Reading manifest data: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/read?lang=js
• Getting resources from a manifest: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/get-resources?lang=js
• Attaching and signing a manifest: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/build?lang=js

Node.js

@cdmurph32 to review

• Setup: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/setup/?lang=node
• Reading manifest data: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/read?lang=node
• Getting resources from a manifest: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/get-resources?lang=node. NOTE: This does not have any code currently, because I couldn't find an example or test code anywhere.
• Attaching and signing a manifest: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/build?lang=node

Notes

To make reviewing easier for developers, I moved all the code into separate files in the docs/tasks/includes directory:

• JavaScript code is in files named _javascript-*.md
• C++ code is in files named _cpp-*.md
• Node.js code is in files named _node-*.md
• Python code is in files named _python-*.md
• Rust code is in files named _rust-*.md

Each language has four files, one for each task:

• Preliminary setup: *-setup.md
• Reading manifest data: *-read.md
• Getting resources from a manifest: *-get-resources.md
• Attaching a manifest to an asset and signing it: *-build.md

[github-actions]

🚀 Deployed on https://deploy-preview-176--cai-open-source.netlify.app

[tmathern]

https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/build/?lang=python : FROM SIGNING is all lower case in the doc, but I think that's not right.

Otherwise, LGTM.

[cdmurph32]

I'm not sure what wasm support means with the check boxes. The almost the entire SDK supports wasm. The only major gap is openSSL signing and verification for ES512. Does that column mean JavaScript?

[crandmck]

I'm not sure what wasm support means with the check boxes. The almost the entire SDK supports wasm. The only major gap is openSSL signing and verification for ES512. Does that column mean JavaScript?

@cdmurph32 I'm not sure what you're referring to, perhaps the Rust release notes...? That's not part of this PR.

I'm asking you to review these pages:

• Setup: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/setup/?lang=node
• Reading manifest data: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/read?lang=node
• Getting resources from a manifest: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/get-resources?lang=node. NOTE: This does not have any code currently, because I couldn't find an example or test code anywhere.
• Attaching and signing a manifest: https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/build?lang=node

In particular, "Getting resources" needs something!

The relevant files in the PR are:

• Setup: docs/tasks/includes/_node-setup.md
• Reading manifest data: docs/tasks/includes/_node-read.md
• Getting resources from a manifest: docs/tasks/includes/_node-get-resources.md
• Attaching a manifest to an asset and signing it: docs/tasks/includes/_node-build.md

[crandmck]

https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/build/?lang=python : FROM SIGNING is all lower case in the doc, but I think that's not right.

Oops, that whole section was essentially a duplicate of the previous code block, that I forgot to remove.... I deleted it, so it should look better now.

[emensch]

This setup works, but I think it would be useful to demonstrate how to include the library when installed locally (e.g. via npm). For the library itself, that just looks like:

import { createC2pa } from 'c2pa':

But it gets a little tricker for the wasmSrc and workerSrc, which need to be made available as static assets that can be fetched at runtime. The best way to do that will vary depending on the build system. For example, vite has an "explicit URL imports" feature that we use in our minimal-ts-vite example.

[crandmck]

OK, I added this, see https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/setup/?lang=js

[tmathern]

For nodejs:

https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/setup/?lang=node

• import { readFile } from 'node:fs/promises'; looks unusual, but if it's in our code this way and works I would leave it (more usual is ... from fs.promises)

https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/read/?lang=node

• You may want to add that the path param needs to be a valid path (since we don't revalidate in the example), and mimeType a valid and supported mimetype (again because in the example we don't revalidate and/or check for undefined/null)

https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/build/?lang=node

• FROM SIGNING is all uppercase somewhere in that page.
• If you have an asset file's data loaded into memory, you can sign the the asset using the loaded stream (buffer). Streams are more native for node (and js), so you can be a little shorter here in the explanation: If you have an asset file's data loaded into a stream, you can use it to sign the asset

https://deploy-preview-176--cai-open-source.netlify.app/docs/tasks/get-resources/?lang=node

• I didn't find examples/test either. But if we want to showcase it, I think we can get inspiration from the js code (the first few lines).

cc @cdmurph32