Create command to append events

[mattbishop]

Three ways to append an event:

• fact - no additional data required.
• serial - requires a previous event id or ledger mark
• atomic - requires a selector id

The body of the command is the full event:

{
  "entity": "tennis",
  "event": "Game Started",
  "key": "2023_winter_classic",
  "meta": { },
  "data": "the data"
}

evently append -s <event-id> '{json event}'

[evert]

Some questions about this task:

1. evently append is the only command so far that's not namespaced. Is that what you want here? Personally I think the namespaces are a little ugly and I would completely get rid of them (for example evently list-entities is better than evently registry:list-entities).
2. The -s <eventid> argument, does that refer to the event in the body? Or does is the -s argument a boolean flag?
3. The {json event} argument, does that go into data?

[mattbishop]

I thought the namespaces were required by oclif? I'm probably wrong about that. We should be consistent though. One good thing about name spacing is that it is easier to discover:

evently registry will give back all the registry commands.

[mattbishop]

About the append flags, -s is short for --selector which is what append atomically expects. Maybe this should be more scoped, like:

evently append:atomic --selector fjgjtu58fjr4lg8kg5 '{"entity":"tennis","event":"Game Started","key":"Winter_classic-2023","meta":{},"data":{"players":["Matt","Evert"]}}'

evently append:fact '{"entity":"tennis","event":"Rain Started","key":"Winter_classic-2023","meta":{},"data":"heavy"}'

evently append:serial --previous 33jfngj64lflhefge3 '{"entity":"tennis","event":"Ball Returned","key":"Winter_classic-2023","meta":{},"data":{"player":"Matt"}'

This way one can get help with the specific append type.

[mattbishop]

On a side note, I don't expect people to be typing the append commands so much as using them to load data and develop. I can easily imagine a batch append command that loads a set of facts via the CLI in a script.

[evert]

I defnitely agree consistency is good, so ill leave it up to you what you prefer. Personally testing the library i found it a bit annoying to need a level of nesting to discover commands while there are only handful.

But happy to stick to that format!

[evert]

Two more thoughts:

1. How would like to deal with validating the JSON input? I assume we can use the schema, but maybe you have some thoughts around how we use the schema. One idea is I download it from the server every time we do an append command. We can also include it in the package during build time.
2. I would love to support JSON5 here (and convert the data to JSON when we submit it to the server). It will make entering data much easier. JSON is valid JSON5, so it just makes more things syntactically valid.

[mattbishop]

The append types vend their schema with GET, so GET https://preview.evently.cloud/append/fact returns the JSON schema for that append method. The other two atomic and serial work the same way. I don't have a mechanism for individual event schemas, but that's coming later.

JSON5 inputs sound great! I can see this is a great use case for integration tests that have comments and other things in the file. What do you think as a way to support it in the CLI? I am curious about adding this into the server itself too so one could specify JSON5 in the append and selector requests. This would be a good first step.

[evert]

Ok, so what ill do is for appending is that I'll always download the json schema before submitting, so I can use AJV to validate the input.