add: aip, a story resource

AGENT.md

@@ -1,5 +1,14 @@
 # Development guide
 
+IMPORTANT: Read @README.md, @aip.md.
+
+## Best practices
+
+Do not read generated files, except for debugging purposes.
+
+After making a change, check the project for diagostnics, and if applicable, run
+related build and test commands.
+
 ## Backend/Golang
 
 Do not alter go.mod directly, instead, use the CLI tools `go mod tidy`, `go mod
@@ -21,7 +30,8 @@ Prefer to test with real implementations rather than mocks. For example, bring
 up a real HTTP server to test.
 
 Generally conform to resource-oriented design describe in
-https://google.aip.dev/general.
+https://google.aip.dev/general. Read aip.md for a summary. All proto service
+methods should be annotated with google.api.http hints and path variables.
 
 ## Frontend/Typescript
 

buf.lock

@@ -0,0 +1,6 @@
+# Generated by buf. DO NOT EDIT.
+version: v2
+deps:
+  - name: buf.build/googleapis/googleapis
+    commit: 004180b77378443887d3b55cabc00384
+    digest: b5:e8f475fe3330f31f5fd86ac689093bcd274e19611a09db91f41d637cb9197881ce89882b94d13a58738e53c91c6e4bae7dc1feba85f590164c975a89e25115dc

buf.yaml

@@ -3,8 +3,13 @@ version: v2
 lint:
   use:
     - STANDARD
+  except:
+    - RPC_REQUEST_RESPONSE_UNIQUE
+    - RPC_RESPONSE_STANDARD_NAME
 breaking:
   use:
     - FILE
 modules:
   - path: proto
+deps:
+  - buf.build/googleapis/googleapis

go.mod

@@ -3,6 +3,7 @@ module git.tipsy.codes/charles/webstory
 go 1.26.1
 
 require (
+	google.golang.org/genproto/googleapis/api v0.0.0-20241202173237-19429a94021a
 	google.golang.org/grpc v1.70.0
 	google.golang.org/protobuf v1.36.11
 )

go.sum

@@ -26,6 +26,8 @@ golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
 golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
 golang.org/x/text v0.23.0 h1:D71I7dUrlY+VX0gQShAThNGHFxZ13dGLBHQLVl1mJlY=
 golang.org/x/text v0.23.0/go.mod h1:/BLNzu4aZCJ1+kcD0DNRotWKage4q2rGVAg4o22unh4=
+google.golang.org/genproto/googleapis/api v0.0.0-20241202173237-19429a94021a h1:OAiGFfOiA0v9MRYsSidp3ubZaBnteRUyn3xB2ZQ5G/E=
+google.golang.org/genproto/googleapis/api v0.0.0-20241202173237-19429a94021a/go.mod h1:jehYqy3+AhJU9ve55aNOaSml7wUXjF9x6z2LcCfpAhY=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20250115164207-1a7da9e5054f h1:OxYkA3wjPsZyBylwymxSHa7ViiW1Sml4ToBrncvFehI=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20250115164207-1a7da9e5054f/go.mod h1:+2Yz8+CLJbIfL9z73EW45avw8Lmge3xVElCP9zEKi50=
 google.golang.org/grpc v1.70.0 h1:pWFv03aZoHzlRKHWicjsZytKAiYCtNS0dHbXnIdq7jQ=

pkg/api/webstory/v1/api_grpc.pb.go

@@ -11,6 +11,7 @@ import (
 	grpc "google.golang.org/grpc"
 	codes "google.golang.org/grpc/codes"
 	status "google.golang.org/grpc/status"
+	emptypb "google.golang.org/protobuf/types/known/emptypb"
 )
 
 // This is a compile-time assertion to ensure that this generated file
@@ -19,11 +20,11 @@ import (
 const _ = grpc.SupportPackageIsVersion9
 
 const (
-	WebstoryService_StartStory_FullMethodName    = "/webstory.v1.WebstoryService/StartStory"
+	WebstoryService_GetStory_FullMethodName    = "/webstory.v1.WebstoryService/GetStory"
-	WebstoryService_ContinueStory_FullMethodName = "/webstory.v1.WebstoryService/ContinueStory"
+	WebstoryService_ListStories_FullMethodName = "/webstory.v1.WebstoryService/ListStories"
-	WebstoryService_GetStory_FullMethodName      = "/webstory.v1.WebstoryService/GetStory"
+	WebstoryService_CreateStory_FullMethodName = "/webstory.v1.WebstoryService/CreateStory"
-	WebstoryService_ResetStory_FullMethodName    = "/webstory.v1.WebstoryService/ResetStory"
+	WebstoryService_UpdateStory_FullMethodName = "/webstory.v1.WebstoryService/UpdateStory"
-	WebstoryService_StreamStory_FullMethodName   = "/webstory.v1.WebstoryService/StreamStory"
+	WebstoryService_DeleteStory_FullMethodName = "/webstory.v1.WebstoryService/DeleteStory"
 )
 
 // WebstoryServiceClient is the client API for WebstoryService service.
@@ -32,16 +33,16 @@ const (
 //
 // WebstoryService defines the RPC methods for the interactive fiction service
 type WebstoryServiceClient interface {
-	// Start a new story session
+	// GetStory retrieves a story by its resource name.
-	StartStory(ctx context.Context, in *StartStoryRequest, opts ...grpc.CallOption) (*StartStoryResponse, error)
+	GetStory(ctx context.Context, in *GetStoryRequest, opts ...grpc.CallOption) (*Story, error)
-	// Continue the story with user input or choice
+	// ListStories returns a list of stories.
-	ContinueStory(ctx context.Context, in *ContinueStoryRequest, opts ...grpc.CallOption) (*ContinueStoryResponse, error)
+	ListStories(ctx context.Context, in *ListStoriesRequest, opts ...grpc.CallOption) (*ListStoriesResponse, error)
-	// Get the current state of a story
+	// CreateStory creates a new story.
-	GetStory(ctx context.Context, in *GetStoryRequest, opts ...grpc.CallOption) (*GetStoryResponse, error)
+	CreateStory(ctx context.Context, in *CreateStoryRequest, opts ...grpc.CallOption) (*Story, error)
-	// Reset or terminate a story session
+	// UpdateStory updates an existing story.
-	ResetStory(ctx context.Context, in *ResetStoryRequest, opts ...grpc.CallOption) (*ResetStoryResponse, error)
+	UpdateStory(ctx context.Context, in *UpdateStoryRequest, opts ...grpc.CallOption) (*Story, error)
-	// Stream story responses in real-time
+	// DeleteStory deletes a story.
-	StreamStory(ctx context.Context, in *StreamStoryRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[StreamStoryResponse], error)
+	DeleteStory(ctx context.Context, in *DeleteStoryRequest, opts ...grpc.CallOption) (*emptypb.Empty, error)
 }
 
 type webstoryServiceClient struct {
@@ -52,29 +53,9 @@ func NewWebstoryServiceClient(cc grpc.ClientConnInterface) WebstoryServiceClient
 	return &webstoryServiceClient{cc}
 }
 
-func (c *webstoryServiceClient) StartStory(ctx context.Context, in *StartStoryRequest, opts ...grpc.CallOption) (*StartStoryResponse, error) {
+func (c *webstoryServiceClient) GetStory(ctx context.Context, in *GetStoryRequest, opts ...grpc.CallOption) (*Story, error) {
 	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
-	out := new(StartStoryResponse)
+	out := new(Story)
-	err := c.cc.Invoke(ctx, WebstoryService_StartStory_FullMethodName, in, out, cOpts...)
-	if err != nil {
-		return nil, err
-	}
-	return out, nil
-}
-
-func (c *webstoryServiceClient) ContinueStory(ctx context.Context, in *ContinueStoryRequest, opts ...grpc.CallOption) (*ContinueStoryResponse, error) {
-	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
-	out := new(ContinueStoryResponse)
-	err := c.cc.Invoke(ctx, WebstoryService_ContinueStory_FullMethodName, in, out, cOpts...)
-	if err != nil {
-		return nil, err
-	}
-	return out, nil
-}
-
-func (c *webstoryServiceClient) GetStory(ctx context.Context, in *GetStoryRequest, opts ...grpc.CallOption) (*GetStoryResponse, error) {
-	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
-	out := new(GetStoryResponse)
 	err := c.cc.Invoke(ctx, WebstoryService_GetStory_FullMethodName, in, out, cOpts...)
 	if err != nil {
 		return nil, err
@@ -82,34 +63,45 @@ func (c *webstoryServiceClient) GetStory(ctx context.Context, in *GetStoryReques
 	return out, nil
 }
 
-func (c *webstoryServiceClient) ResetStory(ctx context.Context, in *ResetStoryRequest, opts ...grpc.CallOption) (*ResetStoryResponse, error) {
+func (c *webstoryServiceClient) ListStories(ctx context.Context, in *ListStoriesRequest, opts ...grpc.CallOption) (*ListStoriesResponse, error) {
 	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
-	out := new(ResetStoryResponse)
+	out := new(ListStoriesResponse)
-	err := c.cc.Invoke(ctx, WebstoryService_ResetStory_FullMethodName, in, out, cOpts...)
+	err := c.cc.Invoke(ctx, WebstoryService_ListStories_FullMethodName, in, out, cOpts...)
 	if err != nil {
 		return nil, err
 	}
 	return out, nil
 }
 
-func (c *webstoryServiceClient) StreamStory(ctx context.Context, in *StreamStoryRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[StreamStoryResponse], error) {
+func (c *webstoryServiceClient) CreateStory(ctx context.Context, in *CreateStoryRequest, opts ...grpc.CallOption) (*Story, error) {
 	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
-	stream, err := c.cc.NewStream(ctx, &WebstoryService_ServiceDesc.Streams[0], WebstoryService_StreamStory_FullMethodName, cOpts...)
+	out := new(Story)
+	err := c.cc.Invoke(ctx, WebstoryService_CreateStory_FullMethodName, in, out, cOpts...)
 	if err != nil {
 		return nil, err
 	}
-	x := &grpc.GenericClientStream[StreamStoryRequest, StreamStoryResponse]{ClientStream: stream}
+	return out, nil
-	if err := x.ClientStream.SendMsg(in); err != nil {
-		return nil, err
-	}
-	if err := x.ClientStream.CloseSend(); err != nil {
-		return nil, err
-	}
-	return x, nil
 }
 
-// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
+func (c *webstoryServiceClient) UpdateStory(ctx context.Context, in *UpdateStoryRequest, opts ...grpc.CallOption) (*Story, error) {
-type WebstoryService_StreamStoryClient = grpc.ServerStreamingClient[StreamStoryResponse]
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(Story)
+	err := c.cc.Invoke(ctx, WebstoryService_UpdateStory_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *webstoryServiceClient) DeleteStory(ctx context.Context, in *DeleteStoryRequest, opts ...grpc.CallOption) (*emptypb.Empty, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(emptypb.Empty)
+	err := c.cc.Invoke(ctx, WebstoryService_DeleteStory_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
 
 // WebstoryServiceServer is the server API for WebstoryService service.
 // All implementations must embed UnimplementedWebstoryServiceServer
@@ -117,16 +109,16 @@ type WebstoryService_StreamStoryClient = grpc.ServerStreamingClient[StreamStoryR
 //
 // WebstoryService defines the RPC methods for the interactive fiction service
 type WebstoryServiceServer interface {
-	// Start a new story session
+	// GetStory retrieves a story by its resource name.
-	StartStory(context.Context, *StartStoryRequest) (*StartStoryResponse, error)
+	GetStory(context.Context, *GetStoryRequest) (*Story, error)
-	// Continue the story with user input or choice
+	// ListStories returns a list of stories.
-	ContinueStory(context.Context, *ContinueStoryRequest) (*ContinueStoryResponse, error)
+	ListStories(context.Context, *ListStoriesRequest) (*ListStoriesResponse, error)
-	// Get the current state of a story
+	// CreateStory creates a new story.
-	GetStory(context.Context, *GetStoryRequest) (*GetStoryResponse, error)
+	CreateStory(context.Context, *CreateStoryRequest) (*Story, error)
-	// Reset or terminate a story session
+	// UpdateStory updates an existing story.
-	ResetStory(context.Context, *ResetStoryRequest) (*ResetStoryResponse, error)
+	UpdateStory(context.Context, *UpdateStoryRequest) (*Story, error)
-	// Stream story responses in real-time
+	// DeleteStory deletes a story.
-	StreamStory(*StreamStoryRequest, grpc.ServerStreamingServer[StreamStoryResponse]) error
+	DeleteStory(context.Context, *DeleteStoryRequest) (*emptypb.Empty, error)
 	mustEmbedUnimplementedWebstoryServiceServer()
 }
 
@@ -137,20 +129,20 @@ type WebstoryServiceServer interface {
 // pointer dereference when methods are called.
 type UnimplementedWebstoryServiceServer struct{}
 
-func (UnimplementedWebstoryServiceServer) StartStory(context.Context, *StartStoryRequest) (*StartStoryResponse, error) {
+func (UnimplementedWebstoryServiceServer) GetStory(context.Context, *GetStoryRequest) (*Story, error) {
-	return nil, status.Error(codes.Unimplemented, "method StartStory not implemented")
-}
-func (UnimplementedWebstoryServiceServer) ContinueStory(context.Context, *ContinueStoryRequest) (*ContinueStoryResponse, error) {
-	return nil, status.Error(codes.Unimplemented, "method ContinueStory not implemented")
-}
-func (UnimplementedWebstoryServiceServer) GetStory(context.Context, *GetStoryRequest) (*GetStoryResponse, error) {
 	return nil, status.Error(codes.Unimplemented, "method GetStory not implemented")
 }
-func (UnimplementedWebstoryServiceServer) ResetStory(context.Context, *ResetStoryRequest) (*ResetStoryResponse, error) {
+func (UnimplementedWebstoryServiceServer) ListStories(context.Context, *ListStoriesRequest) (*ListStoriesResponse, error) {
-	return nil, status.Error(codes.Unimplemented, "method ResetStory not implemented")
+	return nil, status.Error(codes.Unimplemented, "method ListStories not implemented")
 }
-func (UnimplementedWebstoryServiceServer) StreamStory(*StreamStoryRequest, grpc.ServerStreamingServer[StreamStoryResponse]) error {
+func (UnimplementedWebstoryServiceServer) CreateStory(context.Context, *CreateStoryRequest) (*Story, error) {
-	return status.Error(codes.Unimplemented, "method StreamStory not implemented")
+	return nil, status.Error(codes.Unimplemented, "method CreateStory not implemented")
+}
+func (UnimplementedWebstoryServiceServer) UpdateStory(context.Context, *UpdateStoryRequest) (*Story, error) {
+	return nil, status.Error(codes.Unimplemented, "method UpdateStory not implemented")
+}
+func (UnimplementedWebstoryServiceServer) DeleteStory(context.Context, *DeleteStoryRequest) (*emptypb.Empty, error) {
+	return nil, status.Error(codes.Unimplemented, "method DeleteStory not implemented")
 }
 func (UnimplementedWebstoryServiceServer) mustEmbedUnimplementedWebstoryServiceServer() {}
 func (UnimplementedWebstoryServiceServer) testEmbeddedByValue()                         {}
@@ -173,42 +165,6 @@ func RegisterWebstoryServiceServer(s grpc.ServiceRegistrar, srv WebstoryServiceS
 	s.RegisterService(&WebstoryService_ServiceDesc, srv)
 }
 
-func _WebstoryService_StartStory_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
-	in := new(StartStoryRequest)
-	if err := dec(in); err != nil {
-		return nil, err
-	}
-	if interceptor == nil {
-		return srv.(WebstoryServiceServer).StartStory(ctx, in)
-	}
-	info := &grpc.UnaryServerInfo{
-		Server:     srv,
-		FullMethod: WebstoryService_StartStory_FullMethodName,
-	}
-	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
-		return srv.(WebstoryServiceServer).StartStory(ctx, req.(*StartStoryRequest))
-	}
-	return interceptor(ctx, in, info, handler)
-}
-
-func _WebstoryService_ContinueStory_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
-	in := new(ContinueStoryRequest)
-	if err := dec(in); err != nil {
-		return nil, err
-	}
-	if interceptor == nil {
-		return srv.(WebstoryServiceServer).ContinueStory(ctx, in)
-	}
-	info := &grpc.UnaryServerInfo{
-		Server:     srv,
-		FullMethod: WebstoryService_ContinueStory_FullMethodName,
-	}
-	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
-		return srv.(WebstoryServiceServer).ContinueStory(ctx, req.(*ContinueStoryRequest))
-	}
-	return interceptor(ctx, in, info, handler)
-}
-
 func _WebstoryService_GetStory_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
 	in := new(GetStoryRequest)
 	if err := dec(in); err != nil {
@@ -227,34 +183,77 @@ func _WebstoryService_GetStory_Handler(srv interface{}, ctx context.Context, dec
 	return interceptor(ctx, in, info, handler)
 }
 
-func _WebstoryService_ResetStory_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+func _WebstoryService_ListStories_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
-	in := new(ResetStoryRequest)
+	in := new(ListStoriesRequest)
 	if err := dec(in); err != nil {
 		return nil, err
 	}
 	if interceptor == nil {
-		return srv.(WebstoryServiceServer).ResetStory(ctx, in)
+		return srv.(WebstoryServiceServer).ListStories(ctx, in)
 	}
 	info := &grpc.UnaryServerInfo{
 		Server:     srv,
-		FullMethod: WebstoryService_ResetStory_FullMethodName,
+		FullMethod: WebstoryService_ListStories_FullMethodName,
 	}
 	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
-		return srv.(WebstoryServiceServer).ResetStory(ctx, req.(*ResetStoryRequest))
+		return srv.(WebstoryServiceServer).ListStories(ctx, req.(*ListStoriesRequest))
 	}
 	return interceptor(ctx, in, info, handler)
 }
 
-func _WebstoryService_StreamStory_Handler(srv interface{}, stream grpc.ServerStream) error {
+func _WebstoryService_CreateStory_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
-	m := new(StreamStoryRequest)
+	in := new(CreateStoryRequest)
-	if err := stream.RecvMsg(m); err != nil {
+	if err := dec(in); err != nil {
-		return err
+		return nil, err
 	}
-	return srv.(WebstoryServiceServer).StreamStory(m, &grpc.GenericServerStream[StreamStoryRequest, StreamStoryResponse]{ServerStream: stream})
+	if interceptor == nil {
+		return srv.(WebstoryServiceServer).CreateStory(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: WebstoryService_CreateStory_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(WebstoryServiceServer).CreateStory(ctx, req.(*CreateStoryRequest))
+	}
+	return interceptor(ctx, in, info, handler)
 }
 
-// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
+func _WebstoryService_UpdateStory_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
-type WebstoryService_StreamStoryServer = grpc.ServerStreamingServer[StreamStoryResponse]
+	in := new(UpdateStoryRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(WebstoryServiceServer).UpdateStory(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: WebstoryService_UpdateStory_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(WebstoryServiceServer).UpdateStory(ctx, req.(*UpdateStoryRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _WebstoryService_DeleteStory_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(DeleteStoryRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(WebstoryServiceServer).DeleteStory(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: WebstoryService_DeleteStory_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(WebstoryServiceServer).DeleteStory(ctx, req.(*DeleteStoryRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
 
 // WebstoryService_ServiceDesc is the grpc.ServiceDesc for WebstoryService service.
 // It's only intended for direct use with grpc.RegisterService,
@@ -263,29 +262,27 @@ var WebstoryService_ServiceDesc = grpc.ServiceDesc{
 	ServiceName: "webstory.v1.WebstoryService",
 	HandlerType: (*WebstoryServiceServer)(nil),
 	Methods: []grpc.MethodDesc{
-		{
-			MethodName: "StartStory",
-			Handler:    _WebstoryService_StartStory_Handler,
-		},
-		{
-			MethodName: "ContinueStory",
-			Handler:    _WebstoryService_ContinueStory_Handler,
-		},
 		{
 			MethodName: "GetStory",
 			Handler:    _WebstoryService_GetStory_Handler,
 		},
 		{
-			MethodName: "ResetStory",
+			MethodName: "ListStories",
-			Handler:    _WebstoryService_ResetStory_Handler,
+			Handler:    _WebstoryService_ListStories_Handler,
 		},
-	},
-	Streams: []grpc.StreamDesc{
 		{
-			StreamName:    "StreamStory",
+			MethodName: "CreateStory",
-			Handler:       _WebstoryService_StreamStory_Handler,
+			Handler:    _WebstoryService_CreateStory_Handler,
-			ServerStreams: true,
+		},
+		{
+			MethodName: "UpdateStory",
+			Handler:    _WebstoryService_UpdateStory_Handler,
+		},
+		{
+			MethodName: "DeleteStory",
+			Handler:    _WebstoryService_DeleteStory_Handler,
 		},
 	},
+	Streams:  []grpc.StreamDesc{},
 	Metadata: "webstory/v1/api.proto",
 }

proto/webstory/v1/api.proto

@@ -2,137 +2,170 @@ syntax = "proto3";
 
 package webstory.v1;
 
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/protobuf/empty.proto";
+import "google/protobuf/field_mask.proto";
 import "google/protobuf/timestamp.proto";
 
 option go_package = "git.tipsy.codes/charles/webstory/pkg/api";
 
-// Story represents the current state of an interactive fiction session
-message Story {
-  string session_id = 1; // Unique identifier for this story session
-  string current_scene = 2; // Current scene/location identifier
-  string status = 3; // Current story status (playing, paused, completed)
-}
-
-// Visualization represents an image or visual element to display
-message Visualization {
-  string type = 1; // Type of visualization: portrait, scene, map, etc.
-  string url = 2; // URL or path to the visualization
-  string description = 3; // Description of what should be shown
-}
-
-// Choice represents an option the user can select
-message Choice {
-  string label = 1; // Text displayed on the button
-  string action = 2; // Action to trigger when selected
-  map<string, string> metadata = 3; // Additional metadata (optional)
-}
-
-// Message represents a communication between client and server
-message Message {
-  string id = 1; // Unique message identifier
-  string type = 2; // Message type: user_input, story_text, system, etc.
-  string content = 3; // Message content
-  repeated Choice choices = 4; // Available choices (if any)
-  Visualization visualization = 5; // Associated visualization (if any)
-  google.protobuf.Timestamp created_at = 6; // Timestamp when message was created
-  google.protobuf.Timestamp updated_at = 7; // Timestamp when message was last updated
-}
-
-// ChatHistory represents the conversation history
-message ChatHistory {
-  string session_id = 1;
-  repeated Message messages = 2;
-  google.protobuf.Timestamp created_at = 3; // Timestamp when chat history was created
-  google.protobuf.Timestamp updated_at = 4; // Timestamp when chat history was last updated
-}
-
-// Request for starting a new story
-message StartStoryRequest {
-  string session_id = 1; // Optional: client-provided session ID
-  string initial_scene = 2; // Starting scene or scenario prompt
-  string story_genre = 3; // Genre preferences (fantasy, sci-fi, etc.)
-  map<string, string> options = 4; // Additional configuration options
-  google.protobuf.Timestamp created_at = 5; // Timestamp when request was created
-}
-
-// Response for starting a story
-message StartStoryResponse {
-  string session_id = 1;
-  string status = 2;
-  Message initial_message = 3;
-  map<string, string> metadata = 4;
-  google.protobuf.Timestamp created_at = 5; // Timestamp when response was created
-}
-
-// Request for continuing the story
-message ContinueStoryRequest {
-  string session_id = 1;
-  string action = 2; // User's choice or input
-  string choice_id = 3; // If selecting a specific choice
-  map<string, string> options = 4; // Optional parameters
-  google.protobuf.Timestamp created_at = 5; // Timestamp when request was created
-}
-
-// Response for continuing the story
-message ContinueStoryResponse {
-  string session_id = 1;
-  string status = 2;
-  Message response_message = 3;
-  map<string, string> metadata = 4;
-}
-
-// Request to get story state
-message GetStoryRequest {
-  string session_id = 1;
-}
-
-// Response with current story state
-message GetStoryResponse {
-  string session_id = 1;
-  Story story = 2;
-  repeated Message recent_messages = 3;
-}
-
-// Request to reset/stop a story
-message ResetStoryRequest {
-  string session_id = 1;
-}
-
-message ResetStoryResponse {
-  string session_id = 1;
-  string status = 2;
-}
-
 // WebstoryService defines the RPC methods for the interactive fiction service
 service WebstoryService {
-  // Start a new story session
+  // GetStory retrieves a story by its resource name.
-  rpc StartStory(StartStoryRequest) returns (StartStoryResponse);
+  rpc GetStory(GetStoryRequest) returns (Story) {
+    option (google.api.http) = {get: "/v1/{name=stories/*}"};
+    option (google.api.method_signature) = "name";
+  }
 
-  // Continue the story with user input or choice
+  // ListStories returns a list of stories.
-  rpc ContinueStory(ContinueStoryRequest) returns (ContinueStoryResponse);
+  rpc ListStories(ListStoriesRequest) returns (ListStoriesResponse) {
+    option (google.api.http) = {get: "/v1/stories"};
+    option (google.api.method_signature) = "";
+  }
 
-  // Get the current state of a story
+  // CreateStory creates a new story.
-  rpc GetStory(GetStoryRequest) returns (GetStoryResponse);
+  rpc CreateStory(CreateStoryRequest) returns (Story) {
+    option (google.api.http) = {
+      post: "/v1/stories"
+      body: "story"
+    };
+    option (google.api.method_signature) = "story_id,story";
+  }
 
-  // Reset or terminate a story session
+  // UpdateStory updates an existing story.
-  rpc ResetStory(ResetStoryRequest) returns (ResetStoryResponse);
+  rpc UpdateStory(UpdateStoryRequest) returns (Story) {
+    option (google.api.http) = {
+      put: "/v1/{story.name}"
+      body: "story"
+    };
+    option (google.api.method_signature) = "story";
+  }
 
-  // Stream story responses in real-time
+  // DeleteStory deletes a story.
-  rpc StreamStory(StreamStoryRequest) returns (stream StreamStoryResponse);
+  rpc DeleteStory(DeleteStoryRequest) returns (google.protobuf.Empty) {
+    option (google.api.http) = {delete: "/v1/{name=stories/*}"};
+    option (google.api.method_signature) = "name";
+  }
 }
 
-// Request for streaming story responses
+// Story represents a story resource in the webstory service.
-message StreamStoryRequest {
+message Story {
-  string session_id = 1;
+  option (google.api.resource) = {
-  string action = 2;
+    type: "webstory.googleapis.com/Story"
-  string choice_id = 3;
+    pattern: "stories/{story}"
-  map<string, string> options = 4;
+  };
+
+  // The resource name of the story.
+  // Format: stories/{story}
+  string name = 1 [
+    (google.api.field_behavior) = OUTPUT_ONLY,
+    (google.api.field_behavior) = IDENTIFIER
+  ];
+
+  // The ID of the story, used as the final component of the resource name.
+  string story_id = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // The title of the story.
+  string title = 3 [(google.api.field_behavior) = REQUIRED];
+
+  // The content of the story.
+  string content = 4;
+
+  // The description or summary of the story.
+  string description = 5;
+
+  // Labels for organizing and categorizing the story.
+  repeated string labels = 6;
+
+  // Output only. The time when the story was created.
+  google.protobuf.Timestamp create_time = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. The time when the story was last updated.
+  google.protobuf.Timestamp update_time = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. The version of the story for concurrency control.
+  string etag = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
-// Response for streaming story responses
+// GetStoryRequest is the request message for GetStory RPC.
-message StreamStoryResponse {
+message GetStoryRequest {
-  string session_id = 1;
+  // The resource name of the story to retrieve.
-  Message partial_message = 2; // Partial message being built
+  // Format: stories/{story}
-  Message complete_message = 3; // Complete message when finalized
+  string name = 1 [
-  bool is_final = 4; // Indicates if this is the final chunk
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {type: "webstory.googleapis.com/Story"}
+  ];
+}
+
+// ListStoriesRequest is the request message for ListStories RPC.
+message ListStoriesRequest {
+  // The maximum number of stories to return. The service may return fewer than
+  // this value. If unspecified, at most 50 stories will be returned.
+  // The maximum value is 1000; values above 1000 will be coerced to 1000.
+  int32 page_size = 1;
+
+  // A page token, received from a previous ListStories call.
+  // Provide this to retrieve the subsequent page.
+  // When paginating, all other parameters provided to ListStories must match
+  // the call that provided the page token.
+  string page_token = 2;
+
+  // Optional. A filter expression that filters the stories listed in the response.
+  // Supported fields: title, labels.
+  // Example: labels:"fiction" AND title:"adventure"
+  string filter = 3;
+
+  // Optional. The field to order the results by.
+  // Supported fields: create_time, title.
+  // Default: create_time (descending order).
+  string order_by = 4;
+}
+
+// ListStoriesResponse is the response message for ListStories RPC.
+message ListStoriesResponse {
+  // The list of stories.
+  repeated Story stories = 1;
+
+  // A token, which can be sent as page_token to retrieve the next page.
+  // If this field is omitted, there are no subsequent pages.
+  string next_page_token = 2;
+
+  // The total number of stories matching the filter.
+  // This value may be an estimate.
+  int32 total_size = 3;
+}
+
+// CreateStoryRequest is the request message for CreateStory RPC.
+message CreateStoryRequest {
+  // The ID to use for the story, which will become the final component of
+  // the story's resource name.
+  // This value should be 4-63 characters, and valid characters are
+  // /[a-z][0-9]-/.
+  string story_id = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // The story to create.
+  Story story = 2 [(google.api.field_behavior) = REQUIRED];
+}
+
+// UpdateStoryRequest is the request message for UpdateStory RPC.
+message UpdateStoryRequest {
+  // The story to update.
+  // The story's name field is used to specify the resource to update.
+  Story story = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // The list of fields to update.
+  google.protobuf.FieldMask update_mask = 2;
+}
+
+// DeleteStoryRequest is the request message for DeleteStory RPC.
+message DeleteStoryRequest {
+  // The resource name of the story to delete.
+  // Format: stories/{story}
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {type: "webstory.googleapis.com/Story"}
+  ];
 }